NAME

       mussort - A simple music file sorting program

SYNOPSIS

       mussort [OPTIONS] dir1 dir2 ..

DESCRIPTION

       This is a simple tool that sorts a music collection.

       It recursively searches a directory for MP3, OGG Vorbis and FLAC files, processing them
       one by one. It then reads the information from the file and puts them into a newly sorted
       directory tree, in the form base_directory/ARTIST/ALBUM/FILENAME.  The files are renamed
       to CDn-TRACKNUMBER-ARTIST-TRACKNAME.EXT. TRACKNUMBER is omitted if it isn't found, and CDn
       is only included if it detects multiple discs.

       If you use --compilation then the sorting will differ for those albums that are detected
       to be compilation albums, those will be sorted as base_directory/ALBUM/FILENAME instead.
       mussort will remove directories that end up empty after sorting.

       By default mussort will cache file information in ~/.mussort-cache, which speeds up
       subsequent invocations significantly

OPTIONS

       -h, --help
           Display a short help screen and exit

       --version
           Display version information and exit

       -k, --keepdupes
           When mussort reaches two files with identical names, it will keep both, naming the one
           it finds last with a number at the end (ie.
           TRACKNUMBER-ARTIST-TRACKNAME-DUPENUMBER.EXT). This is the default.  Use --largest and
           --noremove to alter this behaviour.

       -l, --largest
           When mussort reaches two files with identical names, it will remove (delete) the
           smallest file and leave the largest in place.

       -n, --noremove
           When mussort reaches two files with identical names it will ignore one of the files
           (the last one it sees) and not sort it.

       -i, --insensitive
           Makes mussort do case-insensitive searches for directory names. This is useful when
           the case in the name of an artist differs and makes mussort place all the music
           correctly into one directory. This might be a bit slower than normal operation, but
           not much. When using this option there is a chance that directory names will differ
           slightly between different collections (see also --consistent).

           You can combine this option with --compilation if you want to.  You can not combine
           --insensitive with --consistent.

       -s, --consistent
           Makes mussort generate consistent directory names. This is useful to ensure that two
           collections on different machines have the exact same directory layout, so that they
           can be rsynced easily. It avoids directory names that are identical except for the
           casing, and is also consistent between runs, and accross different machines. Unlike
           -i, the performance penalty is almost nonexistant.

           You can combine this option with --compilation if you want to. Note that --compilation
           changes the directory layout, so a collection sorted without --compilation but with
           --consistent will differ from a collection sorted with both --compilation and
           --consistent.  You can not combine --consistent with --insensitive.

       -a, --allowspecial
           This forces mussort to not strip special characters from file and directory names.

       -c, --compilation
           Enables compilation detection. In this mode mussort will go through all files without
           moving them first, sorting them in an internal data structure, then it will attempt to
           detect compilation albums and re-sort members of the compilation albums before finally
           moving files on-disk. Compilation albums are placed into a directory tree matching
           ALBUM/FILENAME instead of ARTIST/ALBUM/FILENAME.

           Note that this mode is a bit slower than normal mode, and it will take a bit longer
           before any actual changes are done. This is because it needs to search through all
           files before it can start to rename them.

       --silentskip
           Makes mussort not output messages about files that it skips (those that are skipped
           are generally badly tagged, or not tagged at all).

       -v, --verbose
           Increases the verbosity of mussort. Supply twice to further increase verbosity.

           If supplied once, extra information about what mussort is doing, such as which
           directory is being processed, will be output (this can be useful in --compilation
           mode, as --compilation won't output anything until after all files have been read).

           If supplied twice, it will also output information about which file is currently being
           read.

       --quiet
           Suppresses all status messages (and the terminal title). Errors will still get
           printed.

       --no-cache
           Disables caching of file information. By default mussort will cache file information
           (such as tags) between runs as that significantly improves speed in susequent
           invocations. If you supply this, mussort will neither write nor read any cache.

           Usually there is very little gain in using this, collections as large as 13 000+ music
           files only have a cache file of ~3.2MB. If you want to get back a little of the space
           the cache file takes, see --cleancache.

       --refresh-cache
           This will enable caching in a 'write-only' mode. That is it will write new information
           to the cache, but it will not use existing information. This can be used as an
           alternative to deleting the entire cache when you have different directories that you
           sort, and only want to re-sort (refresh) one of them.

       --cleancache
           This cleans up the cache. It will go through all entries in the cache and remove
           dangling references, expired data and incomplete data. Incomplete data is added when
           mussort finds a file that has invlalid/empty tags. Those files are still added to the
           cache so that mussort does not have to re-evaluate them each time, but their entries
           contain no valid data.

           This can be useful in a few cases:

           - If you have deleted or mvoed a large amount of music files that mussort has
           previously sorted
           - If you want to save a tiny bit of HD space
           - If you want mussort to re-read information from files that previously contained
           invalid data

           mussort will automatically re-evaluate any expired cache data during runtime, so you
           are never required to run --cleancache.

       --cleantree
           When this parameter is in effect, mussort will attempt to clean up the directory tree
           by removing all empty directories that it hits (in addition to performing its usual
           sorting). Note that this has a rather significant performance impact because mussort
           needs to do a lot of extra readdir() operations, and should only be done if you notice
           a lot of empty directories in your music tree and want them cleaned up.

           Normally mussort will automatically clean directories that are empty as a result of
           sorting, but this option will make it check all directories it finds.

DEPENDENCIES

       mussort can use several libraries and utilities to retrieve tag information.  It requires
       only one for each format, however if multiple methods are available mussort will try each
       in turn if one of them fails.

       It needs:

       For MP3: id3v2 (best), id3info from id3lib, or Audio::File
       For Vorbis: Ogg::Vorbis::Header::PurePerl (best), ogginfo from vorbis-tools, or
       Audio::File
       For FLAC: Audio::File (best) or metaflac

FILES

       ~/.mussort-cache
           The mussort file information cache. Not created if --no-cache is supplied.  You can
           safely remove this file any time if you want to (see also --cleancache).

BUGS AND LIMITATIONS

       If you find a bug, please report it at <http://random.zerodogg.org/mussort/bugs>.

INCOMPATIBILITIES

       None known.

AUTHOR

       mussort is written by Eskild Hustvedt <eskild -at- zerodogg d.ot org>

LICENSE AND COPYRIGHT

       Copyright (C) Eskild Hustvedt 2007, 2008, 2009, 2010, 2011

       This is free software; see the source for copying conditions.  There is NO warranty; not
       even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.