Ubuntu Manpage: mussort - A simple music file sorting program

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

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.