view release on metacpan or  search on metacpan

lib/Astroboy.pod  view on Meta::CPAN

=pod

=head1 NAME

Astroboy - organize mp3 files by album and artist

=head1 DESCRIPTION

Astroboy is a set of tools to organize your mp3 collection on disk.

You can point Astroboy to an mp3 file anywhere on the hard drive, 
and it will look inside it for id3 tags
artist and album, and move the file to ~/music/artist/album/file.

=head2 MOTIVATION

We had a repository of many mp3 files, that needed to be kept in some check,
as to artist names, etc.
This will allow you to organize many many many files.

=head1 ABS MUSIC

You should have a place on disk where you organize your music.
By default this place is ~/music
If you don't want to keep providing as argument to the cli tools this path,
and you keep your music elsewhere, you can symlink to solve the issue.

Imagine you keep your mp3s in '/usr/share/music', and you have these users 
who will be using astroboy to arrange the music in the same place, 'joe', 'root', 'jane'.
Do this, as root:

   ln -s /usr/share/music /home/joe/music
   ln -s /usr/share/music /home/jane/music
   ln -s /usr/share/music /root/music
   chown joe.joe /home/joe/music
   chown jane.jane /home/jane/music

That is an example of what you would do.

=head1 USING ASTROBOY

You call astroboy via the command line.
   
   astroboy

You can provide as argument a directories or files.

   astroboy ./album_dir   
   astroboy ./musicfiles/file1.mp3

Directories are expected to be albums, with a set of mp3 files.
Files are expected to be mp3 files with album and artist id3 tags.

=head2 Sorting albums and files

Astroboy can be told to sort an album or a file.

What's the difference?
An album is a collection of files, of which most are mp3 files.
A file must be an mp3 file.

When we sort an album, it's really just a directory that we try to interpret
as a colleciton of files. We run heuristics to findout what the album and artist is for all
the files therein.

=head1 TOUBLESHOOTING

=head2 Albums and files that won't sort

=head3 Albums won't sort if:

Most files are not mp3 files.
The files do not have album and artist id3 tags.
All mp3 files must have the same artist and album tags.

=head3 Solutions

You may have par2 files and txt files that ammount to more than the count of mp3 files. 
Delete the par2 files, and run astroboy again.

   rm album/*par2 album/*PAR2
   astroboy album/

Also make sure the files have album and artist id3 tags.

=head2 Making sure files have artist and album tags

Maybe the mp3 files are missing album and artist tags?

   id3info album/*mp3

If so, you can place the id3tag, and run astroboy again:

   id3tag --album="Super" --artist="The Best" ./album/*mp3
   astroboy album/