paulstretch

🎮 Live Demo | 📦 NPM Package | 📖 Documentation

Extreme time-stretching for audio files in the browser using Web Audio API. This library implements Paul's Extreme Sound Stretch algorithm (PaulStretch) to create dramatic time stretching effects while maintaining sound quality.

🚀 Try It Now!

→ Launch the Interactive Demo

Experience the power of extreme audio stretching directly in your browser. Upload any audio file and stretch it up to 50x its original length!

Features

• 🎵 Browser-based audio processing
• ⚡ Asynchronous processing
• 🎚️ Adjustable stretch factor and window size
• 📱 Works with Files, Blobs, and URL strings
• 🌐 UMD module support
• 🔧 Customizable AudioContext

Installation

npm install paulstretch

Usage

Basic Example

import PaulStretch from 'paulstretch';
async function stretchAudio() {
    // Initialize with default settings (8x stretch, 0.25s window)
    const ps = new PaulStretch();
    try {
        // Load audio file
        const audioBuffer = await ps.loadAudio('path/to/audio.mp3');
        // Process the audio
        const stretchedBuffer = await ps.stretch(audioBuffer);
    // Use the stretched audio buffer...
    } catch (error) {
        console.error('Error processing audio:', error);
    }
}

Custom Configuration

const options = {
    stretchFactor: 10.0, // Stretch audio to 10x original length
    windowSize: 0.5, // Window size in seconds
    audioContext: CustomAudioContext // Optional custom AudioContext
};
const ps = new PaulStretch(options);

Simple File Processing

<input type="file" id="audioInput" accept="audio/*">
<button id="playButton">Stretch & Play</button>
<button id="downloadButton">Stretch & Download</button>
<audio id="player" controls></audio>

const fileInput = document.getElementById('audioInput');
const playButton = document.getElementById('playButton');
const downloadButton = document.getElementById('downloadButton');
const player = document.getElementById('player');

const ps = new PaulStretch({ stretchFactor: 8.0 });

// One-line stretch and play
playButton.addEventListener('click', async () => {
    if (fileInput.files[0]) {
        await ps.processAndPlay(fileInput.files[0]);
    }
});

// One-line stretch and download
downloadButton.addEventListener('click', async () => {
    if (fileInput.files[0]) {
        await ps.processAndDownload(fileInput.files[0], 'my-stretched-audio.wav');
    }
});

// For audio player
document.getElementById('playerButton').addEventListener('click', async () => {
    if (fileInput.files[0]) {
        const audioBuffer = await ps.loadAudio(fileInput.files[0]);
        const stretched = await ps.stretch(audioBuffer);
        player.src = await ps.toUrl(stretched);
    }
});

Even Simpler Examples

// Just stretch and play - that's it!
await ps.processAndPlay('audio.mp3');

// Just stretch and download - that's it!
await ps.processAndDownload('audio.mp3', 'stretched.wav');

// Get a URL for embedding in audio elements
const audioBuffer = await ps.loadAudio('audio.mp3');
const stretched = await ps.stretch(audioBuffer);
const audioUrl = await ps.toUrl(stretched);
document.querySelector('#player').src = audioUrl;

API Reference

PaulStretch Class

Constructor Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | stretchFactor | number | 8.0 | The amount to stretch the audio (e.g., 8.0 = 8x longer) | | windowSize | number | 0.25 | Size of the processing window in seconds | | audioContext | AudioContext | window.AudioContext | Custom AudioContext instance |

Methods

Core Methods

loadAudio(input)

• Parameters:
  • input: File | Blob | string (URL)
• Returns: Promise
• Description: Loads and decodes audio from various input sources

stretch(audioBuffer)

• Parameters:
  • audioBuffer: AudioBuffer
• Returns: Promise
• Description: Performs the time-stretching operation on the provided audio buffer

Utility Methods

toBlob(audioBuffer, format = 'audio/wav')

• Parameters:
  • audioBuffer: AudioBuffer - The stretched audio buffer
  • format: string - Audio format (default: 'audio/wav')
• Returns: Promise
• Description: Converts AudioBuffer to a downloadable audio blob

toUrl(audioBuffer, format = 'audio/wav')

• Parameters:
  • audioBuffer: AudioBuffer - The stretched audio buffer
  • format: string - Audio format (default: 'audio/wav')
• Returns: Promise
• Description: Creates an object URL from the AudioBuffer for use in audio elements

play(audioBuffer)

• Parameters:
  • audioBuffer: AudioBuffer - The stretched audio buffer
• Returns: Promise
• Description: Plays the stretched audio directly through the browser's audio output

download(audioBuffer, filename = 'stretched-audio.wav', format = 'audio/wav')

• Parameters:
  • audioBuffer: AudioBuffer - The stretched audio buffer
  • filename: string - Name of the downloaded file
  • format: string - Audio format
• Returns: Promise
• Description: Triggers download of the stretched audio as a file

Convenience Methods

processAndPlay(input)

• Parameters:
  • input: File | Blob | string (URL)
• Returns: Promise
• Description: One-step method to load, stretch, and play audio

processAndDownload(input, filename = 'stretched-audio.wav', format = 'audio/wav')

• Parameters:
  • input: File | Blob | string (URL)
  • filename: string - Name of the downloaded file
  • format: string - Audio format
• Returns: Promise
• Description: One-step method to load, stretch, and download audio

Technical Details

The extreme stretching algorithm (based on PaulStretch) works by:

1. Breaking the audio into overlapping windows
2. Applying spectral processing to each window
3. Reconstructing the stretched audio using overlap-add synthesis

This implementation uses Web Audio API for processing and is optimized for browser environments, delivering extreme time-stretching capabilities directly in your web applications.

Browser Compatibility

• Chrome 66+
• Firefox 75+
• Safari 14.1+
• Edge 79+

Development

Building from Source

# Install dependencies
npm install
# Run tests
npm test
# Build distribution files
npm run build
# Running Tests
npm test