Music Feature Analyzer #

A Flutter package to extract song metadata and AI-powered music features from audio files on Android and iOS.

Get title, artist, album, duration, bitrate, album art, genre, and more from local files—then run optional AI analysis for tempo (BPM), mood, instruments, danceability, and 20+ musical features.

Installation #

Add to your pubspec.yaml:

dependencies:
  music_feature_analyzer: ^1.0.3

Then run:

flutter pub get

· License: MIT

Supported platforms #

This package uses native Android (MediaMetadataRetriever) and iOS (AVFoundation) APIs and a TensorFlow Lite model (YAMNet). Desktop and web are not supported.

Quick start #

1. Song metadata (no initialization) #

Get full song details from a file path. No AI model is loaded.

import 'package:music_feature_analyzer/music_feature_analyzer.dart';

// Single file
final song = await MusicFeatureAnalyzer.metadata('/path/to/song.mp3');
if (song != null) {
  print('${song.title} — ${song.artist}');
  print('Duration: ${song.duration} ms');
}

// Multiple files
final songs = await MusicFeatureAnalyzer.extractMetadataBatch([
  '/path/to/song1.mp3',
  '/path/to/song2.m4a',
]);

2. AI features (initialize once) #

Tempo, mood, instruments, energy, danceability, and more. Requires one-time initialize() before analysis.

await MusicFeatureAnalyzer.initialize();

final song = await MusicFeatureAnalyzer.metadata('/path/to/song.mp3');
if (song != null && song.duration > 0) {
  final features = await MusicFeatureAnalyzer.analyzeSong(song);
  if (features != null) {
    print('Tempo: ${features.tempoBpm} BPM');
    print('Mood: ${features.mood}');
    print('Genre: ${features.estimatedGenre}');
    print('Danceability: ${features.danceability}');
  }
}

3. Background processing (keeps UI responsive) #

For multiple songs, use extractFeaturesInBackground. You must pass durationMsByPath (map each file path to its duration in milliseconds). Providing durations avoids per-file metadata reads and ensures accurate analysis for long songs.

final filePaths = ['/path/to/a.mp3', '/path/to/b.mp3'];
final durationMsByPath = {
  '/path/to/a.mp3': 240000,  // 4 minutes
  '/path/to/b.mp3': 180000,  // 3 minutes
};

final results = await MusicFeatureAnalyzer.extractFeaturesInBackground(
  filePaths,
  durationMsByPath: durationMsByPath,
  onProgress: (current, total) => print('$current / $total'),
  onSongUpdated: (path, features) => { /* update UI */ },
  onCompleted: () => print('Done'),
  onError: (error) => print('Error: $error'),
);
// results[path] == ExtractedSongFeatures? for each path

If you have a list of SongModel (e.g. from metadata), build the map like this:

final durationMsByPath = { for (final s in songs) s.filePath: s.duration };

Data models #

SongModel (metadata) #

ExtractedSongFeatures (AI analysis) #

From analyzeSong(), analyzeSongs(), or extractFeaturesInBackground():

API reference #

How analysis works #

• Metadata — Read from the file via native Android/iOS APIs. No model load.
• Short or unknown duration — One short segment (~0.975 s) from the middle.
• Duration ≥ 30 s — Three long segments (6 s each) from the middle of each third of the song (D/6, D/2, 5D/6). YAMNet uses the first 0.975 s of each; all other features (tempo, beat, energy, loudness, danceability, spectral, etc.) use the full 6 s for accuracy. Numeric features are averaged across the three parts; categorical (genre, mood) come from the highest-confidence part.
• Background — extractFeaturesInBackground runs heavy work in a separate isolate. You must pass durationMsByPath; no per-file metadata read is performed.

Requirements #

• Flutter 3.0.0+, Dart 3.8.1+
• Android API 21+
• iOS 12.0+
• Platforms: Android and iOS only (no desktop or web)

Formats: MP3, WAV, FLAC, AAC, M4A, OGG, WMA, OPUS, AIFF, ALAC (and other platform-supported formats).

For media library access, configure permissions in your app. See BUILD_COMPATIBILITY.md for setup.

More information #

• CHANGELOG.md — Version history
• example/README.md — Full example app
• Pub.dev
• GitHub
• Issues

Music Feature Analyzer · MIT License · P M JESIL