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 across different machines. Unlike -i, the performance penalty is almost nonexistent.

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.

--dry-run

Just output what would be done, without actually doing it.

--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).

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.