Smart Audio Diff

A TypeScript audio diffing library for comparing WAV audio files and their transcripts. Computes differences between audio waveforms and text transcripts with detailed segment analysis.

Features:

• 🔊 Compare Audio Waveforms: Detects differences between two WAV files.
• 🎚️ Volume Normalization: Automatically normalizes audio levels before comparison to handle volume differences.
• ⏱️ Audio Alignment: Automatically aligns audio files to account for timing offsets.
• 🎛️ Dynamic Sample Rate: Supports WAV files of various sample rates (e.g., 16kHz, 44.1kHz, 48kHz).
• 📝 Transcript Comparison: Compare text transcripts using diff-match-patch.
• 📊 Detailed Analysis: Get segment information with precise timing (start/end in seconds).
• 🚀 Pure TypeScript: Full type safety and lightweight.
• 📦 ESM-first: Modern module structure.

Installation

npm install smart-audio-diff

Prerequisites

This package works with WAV audio files. Ensure your audio files are in WAV format before using this library.

Usage

Basic Comparison

Compare two WAV audio files. The library will automatically normalize volume and align the audio tracks before comparing.

import { compareAudio } from 'smart-audio-diff';

async function compareSongs() {
  try {
    const diff = await compareAudio('./song_original.wav', './song_modified.wav');
    
    console.log('Detected Offset:', diff.detectedOffset);
    console.log('Waveform Segments:', diff.segments);
    // Output: [
    //   { start: 0, end: 2.5, type: 'unchanged' },
    //   { start: 2.5, end: 5.1, type: 'added' },
    //   { start: 5.1, end: 10.0, type: 'unchanged' }
    // ]
  } catch (error) {
    console.error('Error comparing audio:', error.message);
  }
}

compareSongs();

With Transcripts

Compare audio files along with their text transcripts:

import { compareAudio } from 'smart-audio-diff';

async function compareWithText() {
  const diff = await compareAudio(
    './audio1.wav',
    './audio2.wav',
    {
      transcriptA: 'The quick brown fox jumps over the lazy dog',
      transcriptB: 'The quick brown fox jumps over the lazy cat'
    }
  );

  console.log('Audio Diff:', diff.segments);
  console.log('Transcript Diff:', diff.transcriptDiff);
  // Output: [
  //   'UNCHANGED: The quick brown fox jumps over the lazy ',
  //   'REMOVED: dog',
  //   'ADDED: cat'
  // ]
}

compareWithText();

Return Value

The compareAudio function returns a DiffResult object:

interface DiffResult {
  segments: DiffSegment[];        // Waveform diff segments with timing
  transcriptDiff: string[];       // Transcript differences as strings
  waveformDiff: number[];         // Raw waveform diff data
  detectedOffset: number;         // Time offset in seconds detected between files
}

interface DiffSegment {
  start: number;                  // Start time in seconds
  end: number;                    // End time in seconds
  type: 'unchanged' | 'added' | 'removed' | 'rephrased';
}

API Reference

compareAudio(fileA, fileB, options?)

Compares two audio files and optionally their transcripts.

Parameters:

• fileA (string) - Path to the first WAV audio file
• fileB (string) - Path to the second WAV audio file
• options (optional object)
  • transcriptA (string) - Transcript of first audio
  • transcriptB (string) - Transcript of second audio

Returns: Promise<DiffResult> - Comparison results with segments, transcript diffs, and detected offset.

Throws: Error if files don't exist or are invalid formats.

Example:

const result = await compareAudio('./before.wav', './after.wav', {
  transcriptA: 'Original text',
  transcriptB: 'Modified text'
});

License

MIT © Zyam

Contact & Support

• Author: Zyam

Happy diffing! 🎵