{"id":31274084,"url":"https://github.com/willibrandon/ferrous-waves","last_synced_at":"2026-05-09T16:04:05.317Z","repository":{"id":315169145,"uuid":"1058385184","full_name":"willibrandon/ferrous-waves","owner":"willibrandon","description":"Audio analysis library for Rust with FFT, onset detection, tempo estimation, and MCP integration","archived":false,"fork":false,"pushed_at":"2025-09-17T05:03:49.000Z","size":159,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-17T05:33:50.915Z","etag":null,"topics":["audio-analysis","audio-processing","beat-tracking","fft","mcp","onset-detection","rust","signal-processing","spectrogram","tempo-estimation"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/willibrandon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-17T02:52:28.000Z","updated_at":"2025-09-17T05:03:52.000Z","dependencies_parsed_at":"2025-09-17T05:34:49.210Z","dependency_job_id":"4f097feb-7c37-416b-a72e-35fc9427ea6b","html_url":"https://github.com/willibrandon/ferrous-waves","commit_stats":null,"previous_names":["willibrandon/ferrous-waves"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/willibrandon/ferrous-waves","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willibrandon%2Fferrous-waves","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willibrandon%2Fferrous-waves/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willibrandon%2Fferrous-waves/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willibrandon%2Fferrous-waves/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/willibrandon","download_url":"https://codeload.github.com/willibrandon/ferrous-waves/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willibrandon%2Fferrous-waves/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276661851,"owners_count":25682025,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-23T02:00:09.130Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio-analysis","audio-processing","beat-tracking","fft","mcp","onset-detection","rust","signal-processing","spectrogram","tempo-estimation"],"created_at":"2025-09-23T22:34:23.600Z","updated_at":"2025-09-23T22:34:24.667Z","avatar_url":"https://github.com/willibrandon.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ferrous Waves\n\nHigh-fidelity audio analysis bridge for development workflows. Analyze audio files, extract metrics, and integrate with AI tools through MCP.\n\n## Features\n\n- **Multi-format Support**: WAV, MP3, FLAC, OGG, M4A\n- **Spectral Analysis**: FFT/STFT, mel-scale spectrograms, spectral features\n- **Temporal Analysis**: Tempo detection, beat tracking, onset detection\n- **Pitch Detection**: YIN/PYIN algorithms, vibrato analysis, pitch tracking\n- **Perceptual Metrics**: LUFS loudness measurement (EBU R 128), true peak detection, dynamic range analysis\n- **Content Classification**: Speech/music/silence detection with confidence scores\n- **Musical Analysis**: Key detection with confidence, chord progression, harmonic complexity\n- **Quality Assessment**: SNR, THD, clipping detection, noise floor, and reliability scoring\n- **Segment Analysis**: Temporal structure detection, pattern recognition, coherence analysis\n- **Audio Fingerprinting**: Similarity detection, duplicate finding, content identification\n- **Visualization**: Waveforms, spectrograms, power curves (base64 encoded)\n- **MCP Integration**: Direct integration with AI assistants via Model Context Protocol\n- **Content-based Caching**: Fast re-analysis with BLAKE3 hashing\n- **CLI Interface**: Command-line tools for batch processing and automation\n\n## Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/willibrandon/ferrous-waves\ncd ferrous-waves\n\n# Build the project\ncargo build --release\n\n# Run tests\ncargo test\n```\n\n## Usage\n\n### CLI Commands\n\n```bash\n# Analyze a single audio file\nferrous-waves analyze audio.mp3 --format json\n\n# Extract tempo\nferrous-waves tempo song.wav --show-beats\n\n# Detect onsets\nferrous-waves onsets track.flac --format csv\n\n# Compare two audio files\nferrous-waves compare file1.mp3 file2.mp3\n\n# Batch process multiple files\nferrous-waves batch ./music --pattern \"*.mp3\" --parallel 4\n\n# Start MCP server\nferrous-waves serve\n```\n\n### Library Usage\n\n```rust\nuse ferrous_waves::{AudioFile, AnalysisEngine};\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    // Load audio file\n    let audio = AudioFile::load(\"song.mp3\")?;\n\n    // Create analysis engine\n    let engine = AnalysisEngine::new();\n\n    // Run analysis\n    let result = engine.analyze(\u0026audio).await?;\n\n    // Access results\n    println!(\"Tempo: {:?} BPM\", result.temporal.tempo);\n    println!(\"Peak amplitude: {}\", result.summary.peak_amplitude);\n    println!(\"Loudness: {:.1} LUFS\", result.perceptual.loudness_lufs);\n    println!(\"True peak: {:.1} dBFS\", result.perceptual.true_peak_dbfs);\n    println!(\"Average pitch: {:?} Hz\", result.pitch.mean_pitch);\n    println!(\"Vibrato: {:?}\", result.pitch.vibrato);\n    println!(\"Content type: {:?}\", result.classification.primary_type);\n    println!(\"Audio quality score: {:.1}%\", result.quality.overall_score * 100.0);\n    println!(\"Fingerprint hash: {:016x}\", result.fingerprint.perceptual_hash);\n\n    Ok(())\n}\n```\n\n### MCP Integration\n\nStart the MCP server:\n```bash\nferrous-waves serve\n```\n\nThe server exposes three tools:\n\n#### `analyze_audio` - Analyze audio files with configurable depth\nParameters:\n- `file_path` (required): Path to audio file\n- `analysis_profile`: Choose analysis depth (default: \"standard\")\n  - `\"quick\"`: Basic metrics only (fastest)\n  - `\"standard\"`: Core audio features\n  - `\"detailed\"`: All analysis modules\n  - `\"fingerprint\"`: Focus on similarity detection\n  - `\"mastering\"`: Focus on loudness and quality metrics\n- `return_format`: \"summary\" (default), \"full\", or \"visual_only\"\n- `include_visuals`: Include base64-encoded images (default: false, WARNING: very large)\n- `include_spectral`: Include spectral data arrays (default: false)\n- `include_temporal`: Include temporal data arrays (default: false)\n- `max_data_points`: Limit array sizes for pagination (default: 1000)\n- `cursor`: Continue from previous response's next_cursor\n\nResponse format includes:\n- Audio properties (format, duration, sample rate, channels)\n- Content type and confidence scores\n- Quality metrics (loudness LUFS, true peak, dynamic range)\n- Issues categorized by severity (critical, warnings, info)\n- Fingerprint data for similarity matching\n\n#### `compare_audio` - Compare two audio files\nParameters:\n- `file_a`, `file_b` (required): Paths to audio files\n- `metrics`: Optional comparison metrics to calculate\n\nReturns:\n- Similarity scores: overall, fingerprint, spectral, perceptual, structural (0.0-1.0 scale)\n- Differences: loudness delta, tempo delta, quality delta, key change\n- Match type: Identical, Very Similar, Similar, Different\n- Use case suggestions: \"Same recording\", \"Different master\", \"Cover version\", etc.\n\n#### `get_job_status` - Check analysis job status\nParameters:\n- `job_id` (required): Job ID from previous analysis\n\n## Architecture\n\n```\nsrc/\n├── audio/          # Audio file loading and buffer management\n├── analysis/       # Core analysis engine\n│   ├── spectral/   # FFT, STFT, mel-scale processing\n│   ├── temporal/   # Beat tracking, onset detection\n│   ├── pitch/      # YIN/PYIN pitch detection, vibrato analysis\n│   ├── perceptual.rs # LUFS, dynamic range, psychoacoustic metrics\n│   ├── classification.rs # Speech/music/silence detection\n│   ├── musical.rs  # Key detection, chord progression, harmonic analysis\n│   ├── quality.rs  # Audio quality assessment and issue detection\n│   ├── segments.rs # Segment-based temporal structure analysis\n│   └── fingerprint.rs # Audio fingerprinting and similarity detection\n├── visualization/  # Waveform and spectrogram generation\n├── cache/          # Content-based caching system\n├── mcp/           # MCP server implementation\n└── cli/           # Command-line interface\n```\n\n## Configuration\n\nCache settings can be adjusted when creating an `AnalysisEngine`:\n\n```rust\nuse ferrous_waves::{AnalysisEngine, Cache};\nuse std::time::Duration;\n\nlet cache = Cache::with_config(\n    PathBuf::from(\".cache\"),\n    1024 * 1024 * 100,  // 100MB max size\n    Duration::from_secs(3600),  // 1 hour TTL\n);\n\nlet engine = AnalysisEngine::new().with_cache(cache);\n```\n\n## Performance\n\n- SIMD-accelerated FFT operations (2-3x faster) with automatic CPU feature detection\n- Vectorized window functions and spectrum calculations (5-40x faster)\n- Runtime selection of optimal SIMD instructions (SSE2/AVX/AVX2/AVX-512/NEON)\n- Parallel processing for batch operations\n- Content-based caching reduces re-analysis time\n- Async I/O for non-blocking operations\n\n## Examples\n\nThe `examples/` directory contains runnable demonstrations:\n\n```bash\n# Generate sample audio files\ncargo run --example generate_samples\n\n# Basic analysis\ncargo run --example basic_analysis\n\n# Spectral analysis (FFT/STFT)\ncargo run --example spectral_analysis\n\n# Onset detection\ncargo run --example onset_detection\n\n# Perceptual metrics (LUFS, dynamic range)\ncargo run --example perceptual_analysis\n\n# Content classification (speech/music/silence)\ncargo run --example content_classification\n\n# Musical analysis (key detection, chords)\ncargo run --example musical_analysis\n\n# Audio quality assessment\ncargo run --example quality_assessment\n\n# Segment-based temporal analysis\ncargo run --example segment_analysis\n\n# Audio fingerprinting and similarity detection\ncargo run --example fingerprint_similarity\n\n# Compare two audio files\ncargo run --example compare_files\n\n# Cached analysis demonstration\ncargo run --example cached_analysis\n\n# Batch processing\ncargo run --example batch_processing\n\n# Envelope visualization (creates PNG)\ncargo run --example envelope_visualization\n\n# Pitch detection (YIN/PYIN algorithms)\ncargo run --example pitch_detection\n```\n\nSee [examples/README.md](examples/README.md) for more details.\n\n### Quick Start Example\n```rust\nuse ferrous_waves::{AudioFile, AnalysisEngine};\n\nlet audio = AudioFile::load(\"song.mp3\")?;\nlet engine = AnalysisEngine::new();\nlet result = engine.analyze(\u0026audio).await?;\n\nif let Some(tempo) = result.temporal.tempo {\n    println!(\"BPM: {:.1}\", tempo);\n}\n```\n\n## Contributing\n\nPull requests welcome. Please ensure all tests pass and add tests for new features.\n\n```bash\ncargo test\ncargo fmt -- --check\ncargo clippy --all-targets --all-features -- -D warnings\n```\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwillibrandon%2Fferrous-waves","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwillibrandon%2Fferrous-waves","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwillibrandon%2Fferrous-waves/lists"}