🎵 Music Feature Analyzer #

A comprehensive Flutter package for extracting detailed musical features from audio files using YAMNet AI model and advanced signal processing.

🌟 Overview #

Music Feature Analyzer is a powerful Flutter package that combines Google's YAMNet AI model with advanced signal processing to extract comprehensive musical features from audio files. It provides detailed analysis including instrument detection, genre classification, mood analysis, tempo detection, and much more.

🎯 Key Features #

🤖 AI-Powered Analysis: Uses Google's YAMNet model for instrument detection, genre classification, and mood analysis
🔬 Advanced Signal Processing: Sophisticated DSP algorithms for tempo detection, spectral analysis, and energy calculation
📊 Comprehensive Features: Extracts 20+ musical features including tempo, mood, energy, instruments, and more
⚡ High Performance: Optimized for mobile devices with efficient processing
📱 Cross-Platform: Works seamlessly on both iOS and Android
🎨 Easy Integration: Simple API for quick implementation
🧪 Production Ready: Comprehensive test coverage and zero linting errors

🚀 Quick Start #

Installation #

Add this to your pubspec.yaml:

dependencies:
  music_feature_analyzer: ^1.0.0

📦 Model Files Included: The package includes all necessary AI model files (1.tflite and yamnet_class_map.csv) automatically. You don't need to add any model files to your project assets.

Basic Usage #

import 'package:music_feature_analyzer/music_feature_analyzer.dart';

void main() async {
  // Initialize the analyzer
  await MusicFeatureAnalyzer.initialize();
  
  // Analyze a single song
  final features = await MusicFeatureAnalyzer.analyzeSong('/path/to/song.mp3');
  
  if (features != null) {
    print('🎵 Genre: ${features.estimatedGenre}');
    print('🎵 Tempo: ${features.tempoBpm.toStringAsFixed(1)} BPM');
    print('🎵 Instruments: ${features.instruments.join(', ')}');
    print('🎵 Mood: ${features.mood}');
    print('🎵 Energy: ${features.overallEnergy.toStringAsFixed(2)}');
  }
}

🎵 Supported Features #

🤖 AI-Powered Features (YAMNet) #

Instrument Detection: Piano, Guitar, Drums, Violin, Saxophone, Trumpet, Flute, Clarinet, Organ, Synthesizer, and many more
Genre Classification: Rock, Pop, Jazz, Classical, Electronic, Blues, Country, Hip Hop, Reggae, Metal, Folk, R&B, Soul, Funk, Disco, Techno, House, Trance, Dubstep, Ambient, and more
Mood Analysis: Happy, Sad, Energetic, Calm, Angry, Peaceful, Romantic, Mysterious, Dramatic, Playful, and more
Vocal Detection: Speech, Singing, Choir, Chorus, Chant, and various vocal expressions

🔬 Signal Processing Features #

Tempo Detection: Accurate BPM calculation using autocorrelation and rhythmic pattern analysis
Energy Analysis: Overall energy and intensity calculation
Spectral Features: Centroid, Rolloff, Flux, Brightness analysis
Beat Analysis: Beat strength and danceability calculation
Zero Crossing Rate: Percussiveness and texture detection
Spectral Flux: Onset detection and musical dynamics

📊 Combined Metrics #

Complexity: Musical complexity score (0.0-1.0)
Valence: Emotional positivity (0.0-1.0)
Arousal: Emotional intensity (0.0-1.0)
Confidence: Analysis reliability (0.0-1.0)
Danceability: How danceable the music is (0.0-1.0)

📱 Usage Examples #

Single Song Analysis #

import 'package:music_feature_analyzer/music_feature_analyzer.dart';

class MusicAnalyzer {
  static Future<void> analyzeSong() async {
    // Initialize the analyzer
    await MusicFeatureAnalyzer.initialize();
    
    // Analyze a single song
    final features = await MusicFeatureAnalyzer.analyzeSong('/path/to/song.mp3');
    
    if (features != null) {
      print('🎵 Analysis Results:');
      print('  Title: ${features.tempo}');
      print('  Genre: ${features.estimatedGenre}');
      print('  Tempo: ${features.tempoBpm.toStringAsFixed(1)} BPM');
      print('  Instruments: ${features.instruments.join(', ')}');
      print('  Mood: ${features.mood}');
      print('  Energy: ${features.overallEnergy.toStringAsFixed(2)}');
      print('  Danceability: ${features.danceability.toStringAsFixed(2)}');
      print('  Confidence: ${features.confidence.toStringAsFixed(2)}');
    }
  }
}

Batch Processing #

import 'package:music_feature_analyzer/music_feature_analyzer.dart';

class BatchAnalyzer {
  static Future<void> analyzePlaylist() async {
    // Initialize the analyzer
    await MusicFeatureAnalyzer.initialize();
    
    // List of songs to analyze
    final filePaths = [
      '/path/to/song1.mp3',
      '/path/to/song2.mp3',
      '/path/to/song3.mp3',
    ];
    
    // Analyze multiple songs
    final results = await MusicFeatureAnalyzer.analyzeSongs(
      filePaths,
      onProgress: (current, total) {
        print('Progress: $current/$total');
      },
    );
    
    // Process results
    for (final entry in results.entries) {
      final filePath = entry.key;
      final features = entry.value;
      
      if (features != null) {
        print('🎵 $filePath: ${features.estimatedGenre}');
      }
    }
  }
}

Background Processing #

import 'package:music_feature_analyzer/music_feature_analyzer.dart';

class BackgroundAnalyzer {
  static Future<void> analyzeInBackground() async {
    // Initialize the analyzer
    await MusicFeatureAnalyzer.initialize();
    
    final filePaths = [
      '/path/to/song1.mp3',
      '/path/to/song2.mp3',
      '/path/to/song3.mp3',
    ];
    
    // Extract features in background with UI responsiveness
    final results = await MusicFeatureAnalyzer.extractFeaturesInBackground(
      filePaths,
      onProgress: (current, total) {
        print('Progress: $current/$total');
      },
      onSongUpdated: (filePath, features) {
        print('Updated: $filePath');
      },
      onCompleted: () {
        print('Analysis completed!');
      },
      onError: (error) {
        print('Error: $error');
      },
    );
  }
}

Advanced Configuration #

import 'package:music_feature_analyzer/music_feature_analyzer.dart';

class AdvancedAnalyzer {
  static Future<void> analyzeWithOptions() async {
    // Initialize the analyzer
    await MusicFeatureAnalyzer.initialize();
    
    // Custom analysis options
    final options = AnalysisOptions(
      enableYAMNet: true,
      enableSignalProcessing: true,
      enableSpectralAnalysis: true,
      confidenceThreshold: 0.1,
      maxInstruments: 10,
      verboseLogging: true,
    );
    
    // Analyze with custom options
    final features = await MusicFeatureAnalyzer.analyzeSong(
      '/path/to/song.mp3',
      options: options,
    );
    
    if (features != null) {
      print('🎵 Advanced Analysis:');
      print('  Spectral Centroid: ${features.spectralCentroid.toStringAsFixed(2)} Hz');
      print('  Spectral Rolloff: ${features.spectralRolloff.toStringAsFixed(2)} Hz');
      print('  Zero Crossing Rate: ${features.zeroCrossingRate.toStringAsFixed(3)}');
      print('  Spectral Flux: ${features.spectralFlux.toStringAsFixed(3)}');
      print('  Complexity: ${features.complexity.toStringAsFixed(3)}');
      print('  Valence: ${features.valence.toStringAsFixed(3)}');
      print('  Arousal: ${features.arousal.toStringAsFixed(3)}');
    }
  }
}

Track Extraction Progress #

import 'package:music_feature_analyzer/music_feature_analyzer.dart';

class ProgressTracker {
  // Method 1: Track progress using file paths
  static void trackWithFilePaths(List<String> filePaths) {
    final progress = MusicFeatureAnalyzer.getExtractionProgress(filePaths);
    
    print('📊 Analysis Progress:');
    print('  Total Songs: ${progress['totalSongs']}');
    print('  Analyzed: ${progress['analyzedSongs']}');
    print('  Pending: ${progress['pendingSongs']}');
    print('  Completion: ${progress['completionPercentage'].toStringAsFixed(1)}%');
  }
  
  // Method 2: Track progress using Song objects (for project integration)
  static void trackWithSongObjects(List<dynamic> songs) {
    final progress = MusicFeatureAnalyzer.getExtractionProgressWithSongs(songs);
    
    print('📊 Analysis Progress:');
    print('  Total Songs: ${progress['totalSongs']}');
    print('  Analyzed: ${progress['analyzedSongs']}');
    print('  Pending: ${progress['pendingSongs']}');
    print('  Completion: ${progress['completionPercentage'].toStringAsFixed(1)}%');
  }
}

Get Analysis Statistics #

import 'package:music_feature_analyzer/music_feature_analyzer.dart';

class StatisticsAnalyzer {
  static void getStats() {
    final stats = MusicFeatureAnalyzer.getStats();
    
    print('📊 Analysis Statistics:');
    print('  Total Songs: ${stats.totalSongs}');
    print('  Successful: ${stats.successfulAnalyses}');
    print('  Failed: ${stats.failedAnalyses}');
    print('  Success Rate: ${stats.successRate.toStringAsFixed(1)}%');
    print('  Average Time: ${stats.averageProcessingTime.toStringAsFixed(2)}s');
    print('  Last Analysis: ${stats.lastAnalysis}');
    
    print('🎵 Genre Distribution:');
    for (final entry in stats.genreDistribution.entries) {
      print('  ${entry.key}: ${entry.value}');
    }
    
    print('🎵 Instrument Distribution:');
    for (final entry in stats.instrumentDistribution.entries) {
      print('  ${entry.key}: ${entry.value}');
    }
  }
}

🏗️ Architecture #

📁 Project Structure #

lib/
├── music_feature_analyzer.dart          # Main package export
└── src/
    ├── music_feature_analyzer_base.dart # Core analyzer class
    ├── models/                          # Data models
    │   ├── song_features.dart           # Feature extraction results
    │   └── song_model.dart              # Song data model
    └── services/                        # Core services
        └── feature_extractor.dart       # Main extraction logic

🔧 Core Components #

MusicFeatureAnalyzer: Main API class for feature extraction
FeatureExtractor: Core service for YAMNet and signal processing
ExtractedSongFeatures: Immutable data class for extracted features
SongModel: Data model for song information
AnalysisOptions: Configuration options for analysis
AnalysisStats: Statistics and performance metrics

📊 API Reference #