/ 
App-DrivePlayer-0.2.3
/ App::DrivePlayer::MetadataFetcher

NAME

App::DrivePlayer::MetadataFetcher - Fetch track metadata from iTunes, MusicBrainz, and AcoustID

SYNOPSIS

use App::DrivePlayer::MetadataFetcher;

my $fetcher = App::DrivePlayer::MetadataFetcher->new(
    yield        => sub { ... },          # optional: pump GTK events during waits
    acoustid_key => 'YOUR_KEY',           # optional: enables fingerprint lookup
    token_fn     => sub { 'Bearer ...' }, # optional: required for fingerprinting
);

# Text-based lookup (iTunes first, MusicBrainz fallback, with title cleaning)
my $meta = $fetcher->fetch(title => 'Come Together', artist => 'Beatles');

# Acoustic fingerprint lookup (requires fpcalc + AcoustID key)
my $meta = $fetcher->fetch_by_fingerprint(drive_id => $id);

DESCRIPTION

Tries multiple strategies in order to find metadata for a track:

  1. iTunes Search API with original title/artist (fuzzy, no rate limit).

  2. MusicBrainz with original title/artist (fuzzy ~ operator, progressive relaxation).

  3. Both sources again with a cleaned title (track numbers, remaster tags, feat. credits, and other common junk stripped).

  4. AcoustID acoustic fingerprinting via fpcalc: downloads the first 5 MB of the Drive file, generates a Chromaprint fingerprint, queries AcoustID, then fetches full metadata from MusicBrainz. Requires acoustid_key and token_fn to be set, and fpcalc to be installed (sudo apt install libchromaprint-tools).

METHODS

new

my $f = App::DrivePlayer::MetadataFetcher->new(%args);

Optional args: yield (CodeRef), acoustid_key (Str), token_fn (CodeRef returning a Bearer token string).

fetch

my $hashref = $f->fetch(title => $t, artist => $a, album => $al);

Returns a hashref with any of: title artist album year genre track_number. Returns undef on no match.

fetch_by_fingerprint

my $hashref = $f->fetch_by_fingerprint(drive_id => $id);

Identifies the track by acoustic fingerprint. Returns undef if fpcalc is not installed, no AcoustID key is configured, or no match is found.