The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
MusicRoom-0.40
River stage zero No dependents
++
/ MusicRoom

NAME

MusicRoom - Software for managing digital music

VERSION

Version 0.40

SYNOPSIS

Managing digital music files can be a complicated business, converting between audio formats, ensuring tags are consistent and locating extra data like cover art and lyrics. This package provides a framework for performing these tasks.

The package has been designed to simplify the creation of a collection of scripts to carry out the essential tasks required to manage digital music. A complete set of sample scripts has been distributed with the package. These can be used directly or can be customised to meet your own needs.

NOTES

Much of the work perfomed by the package is implemented using other Perl modules and freely available programs.

Extensively tested on Windows, all the facilities should function under other environments, but there has not yet been any attempt to test on other systems.

This version of the system has been tested for many years in a single setup. However it has not been widely tested on lots of configurations. This means it should be treated as Beta software for most users.

OVERVIEW

Managing your own music on computers can be complex. There are a number of available programs that can help with particular tasks like format conversion or playing music but keeping track of tags and manipulating auditory data in a range of computers can become complex, especially when music is accessed through a variety of mechanisms like DAAP servers and MP3 players.

The MusicRoom package acts as the glue to tie together elements for manipulating tag data, tracking down lyrics and cover art, converting audio formats, keeping CSV duplicates of meta information and copying music files from place to place.

This is an initial version of the package, it has been extensively tested at a single location but has not been widely used in many different environments. If something here does not function how you expect it to please tell me about it.

The Directories

Because the package ties together a number of elements there are three directories that must be clearly defined:

  • The 'room' directory

    Holds the database of music tags, the list of valid artists and song names and directories of any lyric files or cover art

  • The 'tools' directory

    Holds the external programs to manipulate audio data (such as lame to encode as mp3 and normalize to adjust audio volume)

  • The 'scripts' directory

    Holds the Perl scripts that use the MusicRoom package.

The Enabling Scripts

Included in the release are a number of scripts that use the MusicRoom package to perform various tasks. Some of these can be considered as essential elements that perform key tasks, like setting up an inital directory structure, others should best be thought of as "sample implementations" showing how the package can be used.

All scripts have been tested under Windows and most have also been tested on Linux. There should not be anything that is OS specific in this software.

  • mr_setup.pl

    This script will ask a set of questions, configure the system and create the required database files.

  • mr_list_music.pl

    Scans a directory tree looking for music files and lists them in a CSV file. The output file is deliberately structured to allow the fix_tags.pl script to work on it.

    Typically the process of importing music requires three steps: scanning a source; fixing the meta data; importing the data. This script performs the first of these, identifying files of various audio formats, extracting as many tags as it can find and reporting what was found in a file that can be easily edited.

  • mr_fix_tags.pl

    Scan a CSV file that holds tags for a set of music files, check where the tags need to be corrected and provide some automated tools to apply the corrections. The idea is that once this script is happy with a set of tags they are ready to add to the music collection.

    This script is just about usable but by no means complete.

  • mr_publish.pl

    Perform the tasks required to take a validated set of tags in a CSV file (usually generated by renaming a fix_tags file with final).

    This script automates the steps required to add music into the library. It checks that the suggested tags meet all the restrictions (artist is known, year is valid, cover art exists and so on), it then copies the original files into the "best" directory, converts the format, normalises the volume, adds all the tags and places a standard vesrion in the "active" music directory.

  • mr_resample.pl

    Every so often there are significant errors in the tags. This script will regenerate "active" music files based on the latest set of tags. It uses the "best" data as its source.

    The script relies on the bad active files and the entries in the "active list" having been removed. It identifies which entries are missing, locates the associated "best" auidio files and publishes them to the active directory.

  • mr_search_lyrics.pl

    List all the audio files that have a particular word in their lyrics.

  • mr_list_covers.pl

    List where the cover art files are to be found for music in the collection.

  • mr_list_lyrics.pl

    List where the lyric files are to be found for music in the "active set". Produces a CSV file listing the location of the text files that contain the lyrics.

  • mr_lyric_fetch.pl

    Scan a file of music that needs to have lyrics fetched and uses a Perl module to download the appropriate lyrics (if it can find them).

    The file used is essentially the lines identifying missing lyrics from the mr_list_lyrics.pl script.

    It uses Lyrics::Fetcher, so you must install that module before attempting to run the script.

The Modules

There are a number of modules that the package is built on:

  • MusicRoom::LogicalModel

    Define the logical data structure that can be used to explore the information.

  • MusicRoom::Album, MusicRoom::Artist, MusicRoom::Track, MusicRoom::Song, MusicRoom::Zone

    These modules implement objects that come from the music database.

  • MusicRoom::Charts

    Routines for handling music charts

  • MusicRoom::CoverArt

    Routines for locating and attaching cover art for songs

  • MusicRoom::Lyrics

    Routines for locating and attaching cover art for songs

  • MusicRoom::File

    Handling files of various types, for example converting between audio formats

  • MusicRoom::Date

    Handling dates, includes the ability to handle dates before the 1750s

  • MusicRoom::STN

    Generating and using random identifiers for elements such as items and file names

  • MusicRoom::Context

    Handles the grouping of variables, and associated values

  • MusicRoom::Locate

    Using location specifiers in combination with songs (and similar things) to identify associated files (containing for example cover art and lyrics).

  • MusicRoom::Text::CSV

    Handle comma seperated value files. Should be replaced by the real Text::CSV package one day

  • MusicRoom::Text::Nearest

    Find the closest match for a name to a list of valid values

  • MusicRoom::Text::SoundexNG

    A specially tuned Soundex variant that identifies names close to a given one

  • MusicRoom::InitialLists

    Some initial lists of valid artists, song titles and albums

  • MusicRoom::ValidAlbums, MusicRoom::ValidArtists, MusicRoom::ValidSongs

    Process the valid names lists

SUBROUTINES/METHODS

AUTHOR

Steve Hawtin, <steve at tsort.demon.co.uk>

BUGS

Please report any bugs or feature requests to bug-musicroom at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MusicRoom. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc MusicRoom

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2007-2010 Steve Hawtin.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.