bungee-pitch-shift

v1.0.8

Published

5 months ago

High-quality, low-latency pitch shifting and time stretching for Web Audio API using WebAssembly

0High
0Medium
0Low

audio pitch-shift time-stretch web-audio wasm audio-worklet phase-vocoder music sound web-worker offline-processing waveform audio-visualization

Bungee Pitch Shift

High-quality, low-latency pitch shifting and time stretching for Web Audio API using WebAssembly.

Built on the Bungee phase vocoder library, this package provides both a framework-agnostic class-based API and optional React hooks for easy integration.

Features

High Quality: Phase vocoder algorithm for natural-sounding pitch shifts
Low Latency: ~40ms latency using AudioWorklet and WebAssembly
Independent Control: Separate pitch shifting (-12 to +12 semitones) and time stretching (0.5x to 2x speed)
Wet/Dry Mix: Blend processed and original signals
Web Worker Support: Offline processing, file loading, and waveform generation in background threads
Framework Agnostic: Works with vanilla JavaScript or any framework
React Support: Optional React hooks included
TypeScript: Full TypeScript support with type definitions

Installation

npm install bungee-pitch-shift

Setup

After installation, copy the bundled processor to your public directory:

# Copy the bundled processor (includes embedded WASM)
cp node_modules/bungee-pitch-shift/dist/bungee-processor-bundled.js public/

That's it! The bundled processor is completely self-contained:

✅ Includes the AudioWorklet processor
✅ Includes the Emscripten WASM glue code
✅ Includes the embedded WASM binary
✅ No additional files needed

Note: The path assumes your public directory is at public/. Adjust as needed for your project structure (e.g., public/, static/, dist/).

Build Tool Integration

For automated copying during builds, add a postinstall script to your package.json:

{
  "scripts": {
    "postinstall": "cp node_modules/bungee-pitch-shift/dist/bungee-processor-bundled.js public/"
  }
}

Using a CDN

Load the bundled processor from a CDN or remote server:

const pitchShift = await BungeePitchShift.create(audioContext, {
  workletPath: 'https://cdn.example.com/bungee-processor-bundled.js'
});

Benefits:

No need to copy files to your public directory
Better caching and performance via CDN
Simplified deployment
Share across multiple projects

CORS Note: When loading from a different domain, ensure the server sends appropriate CORS headers.

Next.js / Vite / Other Build Tools

Copy the file to your static assets directory:

Next.js:

cp node_modules/bungee-pitch-shift/dist/bungee-processor-bundled.js public/

Vite:

cp node_modules/bungee-pitch-shift/dist/bungee-processor-bundled.js public/

Create React App:

cp node_modules/bungee-pitch-shift/dist/bungee-processor-bundled.js public/

Quick Start

Vanilla JavaScript / TypeScript

import { BungeePitchShift } from 'bungee-pitch-shift';

// Create audio context
const audioContext = new AudioContext();

// Initialize pitch shifter (uses bundled processor by default)
const pitchShift = await BungeePitchShift.create(audioContext);

// Or specify custom path:
// const pitchShift = await BungeePitchShift.create(audioContext, {
//   workletPath: '/bungee-processor-bundled.js'
// });

// Connect to audio graph
sourceNode.connect(pitchShift.node);
pitchShift.connect(audioContext.destination);

// Control parameters
pitchShift.setPitch(5);    // +5 semitones (perfect fourth up)
pitchShift.setSpeed(1.2);  // 20% faster
pitchShift.setMix(0.8);    // 80% wet, 20% dry

// Cleanup when done
pitchShift.dispose();

React

import { usePitchShift } from 'bungee-pitch-shift/react';
import { useRef, useEffect } from 'react';

function AudioPlayer() {
  const audioContext = useRef(new AudioContext()).current;
  const {
    pitchShift,
    initialized,
    updatePitch,
    updateSpeed,
    updateMix,
    info
  } = usePitchShift(audioContext);

  useEffect(() => {
    if (!pitchShift || !initialized) return;

    // Connect to audio graph
    sourceNode.connect(pitchShift.node);
    pitchShift.connect(audioContext.destination);

    return () => {
      pitchShift.disconnect();
    };
  }, [pitchShift, initialized]);

  return (
    <div>
      <h3>Bungee v{info.version}</h3>

      <label>
        Pitch:
        <input
          type="range"
          min="-12"
          max="12"
          step="1"
          onChange={(e) => updatePitch(Number(e.target.value))}
        />
      </label>

      <label>
        Speed:
        <input
          type="range"
          min="0.5"
          max="2"
          step="0.1"
          onChange={(e) => updateSpeed(Number(e.target.value))}
        />
      </label>

      <label>
        Mix:
        <input
          type="range"
          min="0"
          max="1"
          step="0.01"
          onChange={(e) => updateMix(Number(e.target.value))}
        />
      </label>
    </div>
  );
}

Web Worker Utilities

The bungee-pitch-shift/worker module provides Web Worker-based utilities for CPU-intensive audio operations. These tools keep your main thread responsive during heavy processing tasks.

Features

Offline Processing: Process entire audio files with pitch shifting
Audio File Loading: Load and decode audio files off the main thread
Waveform Generation: Generate visualization data without blocking UI
Fully Typed: Complete TypeScript support
Transferable Objects: Efficient zero-copy data transfer

Setup

Copy the bundled worker file to your public directory:

cp node_modules/bungee-pitch-shift/dist/worker/audio-processor.worker.bundle.js public/

Important: Use the .bundle.js file (not .worker.js). The bundle file is self-contained and has all dependencies included.

OfflineProcessor - Batch Audio Processing

Process entire audio files with pitch shifting in a worker thread:

import { OfflineProcessor } from 'bungee-pitch-shift/worker';

const processor = new OfflineProcessor({
  workerPath: '/audio-processor.worker.bundle.js',
  workletPath: '/bungee-processor-bundled.js'
});

// Process audio buffer
const audioContext = new AudioContext();
const processed = await processor.processWithContext(
  audioBuffer,
  audioContext,
  {
    pitch: 5,      // +5 semitones
    speed: 1.2,    // 20% faster
    mix: 1.0,      // 100% wet
    onProgress: (progress) => {
      console.log(`Progress: ${Math.round(progress * 100)}%`);
    }
  }
);

// Cleanup
processor.dispose();

Key Benefits:

Non-blocking: UI remains responsive during processing
Progress tracking: Get real-time updates on processing status
Faster than real-time: No playback constraints

AudioFileLoader - Load Audio Files in Workers

Load and decode audio files without blocking the main thread:

import { AudioFileLoader } from 'bungee-pitch-shift/worker';

const loader = new AudioFileLoader({
  workerPath: '/audio-processor.worker.bundle.js'
});

// Load from URL
const audioContext = new AudioContext();
const audioBuffer = await loader.loadWithContext(
  'https://example.com/audio.mp3',
  audioContext,
  {
    onProgress: (progress) => {
      console.log(`Loading: ${Math.round(progress * 100)}%`);
    }
  }
);

// Or decode raw data
const response = await fetch('audio.mp3');
const arrayBuffer = await response.arrayBuffer();
const decoded = await loader.decodeWithContext(arrayBuffer, audioContext);

// Cleanup
loader.dispose();

Use Cases:

Large file loading without UI freezing
Batch loading multiple files
Pre-loading audio for web apps

WaveformGenerator - Visualization Data

Generate waveform data for audio visualizations:

import { WaveformGenerator } from 'bungee-pitch-shift/worker';

const generator = new WaveformGenerator({
  workerPath: '/audio-processor.worker.bundle.js'
});

// Generate waveform with 1000 samples
const waveform = await generator.generate(audioBuffer, {
  samples: 1000,
  channel: 0,      // Left channel (or -1 for average)
  useRMS: false    // Use peak values
});

// Use waveform.data for rendering
for (let i = 0; i < waveform.data.length; i++) {
  const amplitude = waveform.data[i];
  // Draw visualization bar
}

// Generate for multiple channels
const multiChannel = await generator.generateMultiChannel(audioBuffer, {
  samples: 1000
});

// Quick preview (low resolution)
const preview = await generator.generatePreview(audioBuffer, 100);

// High resolution
const hires = await generator.generateHighRes(audioBuffer);

// Cleanup
generator.dispose();

Waveform Options:

samples: Number of samples in output (default: 1000)
channel: Which channel to use (0 = left, 1 = right, -1 = average all)
useRMS: Use RMS values instead of peaks (default: false)

Worker Utilities

The worker module also exports useful utility functions:

import {
  serializeAudioBuffer,
  deserializeAudioBuffer,
  getTransferables,
  downsampleAudioBuffer,
  validateAudioBuffer,
  formatDuration,
  formatBytes
} from 'bungee-pitch-shift/worker';

// Serialize for efficient transfer
const serialized = serializeAudioBuffer(audioBuffer);
const transferables = getTransferables(serialized);
worker.postMessage({ audioData: serialized }, transferables);

// Downsample for visualization
const waveformData = downsampleAudioBuffer(audioBuffer, 1000);

// Format helpers
console.log(formatDuration(audioBuffer.duration)); // "2:30"
console.log(formatBytes(arrayBuffer.byteLength));  // "1.5 MB"

Worker Configuration

All worker classes accept configuration options:

interface WorkerConfig {
  workerPath?: string;      // Path to worker script
  workletPath?: string;     // Path to bundled AudioWorklet processor
  timeout?: number;         // Operation timeout (ms)

  // Deprecated - no longer needed with bundled processor:
  wasmPath?: string;        // @deprecated
  wasmBinaryPath?: string;  // @deprecated
}

Best Practices

Reuse Worker Instances: Create once, use multiple times
Dispose When Done: Always call .dispose() to clean up
Progress Callbacks: Use for better UX on long operations
Error Handling: Wrap worker calls in try-catch blocks

const processor = new OfflineProcessor();

try {
  const result = await processor.processWithContext(
    audioBuffer,
    audioContext,
    { pitch: 5, speed: 1.0 }
  );
  // Use result...
} catch (error) {
  console.error('Processing failed:', error);
} finally {
  processor.dispose();
}

API Reference