@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

1. Use Web Workers for processing files >30 seconds
2. Enable streaming for files >2 minutes
3. Always call cleanup() after processing
4. Batch process multiple files for efficiency
5. 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.