beat-parser-core

@beat-parser/core

A powerful, production-ready TypeScript library for parsing musical beats and rhythmic patterns from audio data. Built for both browser and Node.js environments with Web Worker support for heavy processing tasks.

Features

🎵 Advanced Beat Detection

• Hybrid algorithm combining onset detection, tempo tracking, and spectral analysis
• Genre-adaptive processing with optimizations for different music styles
• Multi-pass analysis for improved accuracy and confidence scoring
• Variable tempo support for complex musical pieces

🚀 Performance Optimized

• Web Worker support for non-blocking processing
• Streaming processing for large audio files
• Batch processing for multiple files
• Memory efficient with automatic cleanup
• Progressive reporting with real-time progress callbacks

🔧 Developer Friendly

• TypeScript first with comprehensive type definitions
• Plugin system for extensible functionality
• Multiple output formats (JSON, XML, CSV)
• Comprehensive error handling with detailed error messages
• Modern ES modules with CommonJS compatibility

🌐 Universal Compatibility

• Browser support with Web Audio API integration
• Node.js support for server-side processing
• Multiple audio formats: WAV, MP3, FLAC, OGG, M4A
• Configurable sample rates and processing parameters

Quick Start

Installation & Setup

For complete installation instructions, environment setup, and configuration options, see Setup Guide.

npm install @beat-parser/core

Basic Example

import { BeatParser } from '@beat-parser/core';

// Create parser and process audio
const parser = new BeatParser();
const result = await parser.parseBuffer(audioData, {
  targetPictureCount: 16,
  selectionMethod: 'adaptive'
});

console.log('Detected beats:', result.beats.length);
console.log('Tempo:', result.tempo, 'BPM');

// Always cleanup
await parser.cleanup();

Worker Processing

import { BeatParserWorkerClient } from '@beat-parser/core';

const workerClient = new BeatParserWorkerClient();
const result = await workerClient.parseBuffer(audioData, {
  progressCallback: (progress) => console.log(`${progress.percentage}%`)
});
await workerClient.terminate();

Documentation

Core Documentation

• API Reference - Complete API documentation with all methods, types, and examples
• Setup & Installation - Installation instructions, configuration, and environment setup
• Architecture Guide - Technical design, algorithms, and system architecture
• Audio Decoding Guide - Audio format support and decoding details
• Testing Guide - Complete testing documentation and examples
• Contributing Guide - Development setup and contribution guidelines

## Performance Benchmarks

Based on comprehensive testing across multiple platforms:

| Audio Duration | Processing Time | Memory Usage | Typical Results |
|---------------|-----------------|--------------|----------------|
| 5 seconds     | <3 seconds     | <10MB        | 8-12 beats     |
| 30 seconds    | <15 seconds    | <25MB        | 40-60 beats    |
| 2 minutes     | <60 seconds    | <50MB        | 160-240 beats  |
| 5 minutes     | <150 seconds   | <100MB       | 400-600 beats  |

**Key Performance Features:**
- **Web Worker processing**: 40-70% performance improvement
- **Memory efficient**: Automatic cleanup with bounded growth
- **Streaming support**: Process large files without loading everything into memory
- **Real-time capable**: <1.0x processing time for most audio

## Key Classes

### BeatParser
Main parser class for beat detection and audio processing.
```typescript
const parser = new BeatParser(config?);
const result = await parser.parseFile(filePath, options?);

BeatParserWorkerClient

Web Worker client for background processing.

const client = new BeatParserWorkerClient(options?);
const result = await client.parseBuffer(audioData, options?);

For complete API documentation, see API.md

Error Handling

Robust error handling with descriptive messages:

try {
  const result = await parser.parseBuffer(audioData);
} catch (error) {
  if (error.message.includes('Invalid or empty audio data')) {
    // Handle invalid input
  } else if (error.message.includes('Unsupported audio format')) {
    // Handle format issues
  }
  // Full error handling guide in API.md
}

Compatibility

Browsers: Chrome 66+, Firefox 60+, Safari 13.1+, Edge 79+
Node.js: 18.0.0+ with npm 8.0.0+
Audio Formats: WAV, MP3, FLAC, OGG, M4A

For complete compatibility details, see SETUP.md.

Contributing

We welcome contributions! See CONTRIBUTING.md for:

• Development setup instructions
• Code standards and guidelines
• Testing requirements
• Pull request process

Quick Start:

git clone https://github.com/username/beat-parser.git
cd beat-parser
npm install
npm test

Performance Tips

• Use Web Workers for processing files >30 seconds
• Enable streaming for files >2 minutes
• Always call cleanup() after processing
• Batch process multiple files for efficiency
• Adjust confidence threshold based on accuracy needs

For complete performance optimization guide, see API.md.

Troubleshooting

Common solutions:

• Worker not supported: Use main thread BeatParser instead
• Audio file not found: Verify file path and permissions
• Unsupported format: Convert to supported format (WAV, MP3, FLAC, OGG, M4A)
• High memory usage: Use streaming processing and call cleanup()

For complete troubleshooting guide, see Setup Guide.

📚 Documentation

Essential Documentation

• Setup & Installation - Complete setup guide
• API Reference - Full API documentation
• Architecture - Technical design details
• Audio Decoding - Audio format support guide
• Testing - Comprehensive test documentation

Project Resources

• Contributing - How to contribute
• Changelog - Version history

License

MIT License. See LICENSE file for details.

Links

• Examples - Usage examples and demos
• GitHub Issues - Bug reports and feature requests

Developed with ❤️ for the audio processing community.