NAME

Music::DB::Reports - Generate quick reports of a Music::DB database

SYNOPSIS

use Music::DB::Reports;

my $report = Music::DB::Reports->new(-dsn => 'musicdb');

my $albums = $report->album_list(-sort_by => 'artist'); foreach my $album_obj (@$albums) { my $album = $album_obj->album; my $artist = $album_obj->artists; my $year = $album_obj->years;

print join("\t",$album,$artist,$year),"\n";

OVERVIEW

Music::DB::Reports facilitates several different classes of reports. These include full library reports, song, artist, album, genre and bitrate based reports. In general, each report returns arrays of the appropriate objects.

Associated accessor methods are provide full access to the underlying data.

Album Reports

Album reports aggregate songs into albums provide quick, decise views of your collection. These include:

- listing all albums with associated artists and year released
- finding albums that fall below a given bitrate threshold
- finding albums with multiple bitrates

The following methods return a complex data structure. It is suggested that you use provided methods to access the structure as it may change in future releases.

$report->album_list(@options);

Generate a list of all albums. Returns a list of Music::DB::Album objects, each potentially containing Music::DB::Song objects.

Options:
  -sort_order    A sort key. One of artist, album, or year
  -include_songs Boolean true to return songs with the albums

The resulting list can be sorted by artist, album, or year released by passing the sort_order option. In the event that multiple years or artists are contained on the album, the placeholder "Various Artists" or "Various Years" will be used as the search key.

In the interests of memory consumption, the album_list() method returns only the album name, artist, year, and bitrates for each album by default. If you also need access to the song list for each individual album, pass a true value with the -include_songs option.

$report->albums_with_multiple_bitrates(@options)

Display all albums that have songs of different bitrates. Returns a list of Music::DB::Album objects, each potentially containing Music::DB::Song objects.

Options:
  -sort_order      A sort key. One of artist, album, or year
  -include_songs   Boolean true to return songs with the albums

Like album_list(), returned albums can be sorted by passing the sort_order option, and can contain songs if passed the -include_songs option. See album_list() for details.

$report->albums_below_bitrate_threshold(@options)

Display all albums that have ANY songs below a provided bitrate threshold. Returns a list of Music::DB::Album objects, each potentially containing Music::DB::Song objects.

Options:
  -threshold     The bitrate threshold
  -sort_order    A sort key. One of artist, album, or year
  -include_songs Boolean true to return songs with the albums

Like album_list(), returned albums can be sorted by passing the sort_order option, and can contain songs if passed the -include_songs option. See album_list() for details.

Artist Reports

$report->artists_with_multi_genres(@options);

Generate a list of all artists with multiple genres associated to them. Returns an array of Music::DB::DataTypes::Artist objects, each of which contains multiple Music::DB::DataTypes::Genre objects. See the example script eg/artists_with_multiple_genres for a demonstration on accessing this data structure using provided methods.

Song Reports

The following methods provide several song-level reports.

$report->song_list(@options)

Generate a list of all songs. Returns a list of Music::DB::DataTypes::Song objects. This is not particularly useful for large collections and may consume a lot of memory.

Options:
  -sort_order    A sort key. One of artist, album, or year

The resulting list can be sorted by any of the available fields in the song table.

$report->distribution(@options)

Create an histogram showing distribution of albums or songs by year. Requires that the GD module be installed.

Options:
-class       one of albums or songs
-width       desired width of the image in pixels
-height      desired height of the image in pixels
-range       array of year range to display (ie [1950..2004]).
             If not provided, all years in the collection will be used
-background  background color for the image as an [r g b] array reference
-foreground  foreground color for the boxes as an [r g b] array reference
-omit_totals if provided, yearly totals will be omitted

$report->library_size()

Calculate the full size of your library. Returns a hash reference containing the size in kilobytes (Kb), megabytes (MB), and the size in gigabytes (GB).

$report->library_duration()

Calculate the full duration of your library. Returns a hash reference containing the breakdown of the total duration using the hash keys days, minutes, hours, and seconds. For convenience, the total time is also returned as a formatted string of DD::HH::MM::SS under the hash key "total_time".

$report->counts()

Generate simple counts of the primary classes in the library. Returns a hash reference with the following keys: songs, artists, albums, and genres.