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.
- 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
- 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
- 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
- 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
For complete installation instructions, environment setup, and configuration options, see Setup Guide.
npm install beat-parser-core# Configure npm to use GitHub Packages for @sw6820 scope
echo "@sw6820:registry=https://npm.pkg.github.com" >> .npmrc
# Install the package
npm install @sw6820/beat-parser-coreimport { BeatParser } from 'beat-parser-core';
// or from GitHub Packages: import { BeatParser } from '@sw6820/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();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();- 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?);
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
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
}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.
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- 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.
Common solutions:
- Worker not supported: Use main thread
BeatParserinstead - 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.
- Setup & Installation - Complete setup guide
- API Reference - Full API documentation
- Architecture - Technical design details
- Audio Decoding - Audio format support guide
- Testing - Comprehensive test documentation
- Contributing - How to contribute
- Changelog - Version history
MIT License. See LICENSE file for details.
- Examples - Usage examples and demos
- GitHub Issues - Bug reports and feature requests
Developed with ❤️ for the audio processing community.