.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "mussort 1" .TH mussort 1 "2021-01-07" "mussort 0.4" "" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" mussort \- A simple music file sorting program .SH "SYNOPSIS" .IX Header "SYNOPSIS" mussort \fI[\s-1OPTIONS\s0]\fR \fIdir1 dir2 ..\fR .SH "DESCRIPTION" .IX Header "DESCRIPTION" This is a simple tool that sorts a music collection. .PP It recursively searches a directory for \s-1MP3, OGG\s0 Vorbis and \s-1FLAC\s0 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 \&\fIbase_directory/ARTIST/ALBUM/FILENAME\fR. The files are renamed to \&\fICDn\-TRACKNUMBER\-ARTIST\-TRACKNAME.EXT\fR. \s-1TRACKNUMBER\s0 is omitted if it isn't found, and CDn is only included if it detects multiple discs. .PP If you use \-\-compilation then the sorting will differ for those albums that are detected to be compilation albums, those will be sorted as \&\fIbase_directory/ALBUM/FILENAME\fR instead. mussort will remove directories that end up empty after sorting. .PP By default mussort will cache file information in ~/.mussort\-cache, which speeds up subsequent invocations significantly .SH "OPTIONS" .IX Header "OPTIONS" .IP "\fB\-h, \-\-help\fR" 4 .IX Item "-h, --help" Display a short help screen and exit .IP "\fB\-\-version\fR" 4 .IX Item "--version" Display version information and exit .IP "\fB\-k, \-\-keepdupes\fR" 4 .IX Item "-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. \&\fI\s-1TRACKNUMBER\-ARTIST\-TRACKNAME\-DUPENUMBER.EXT\s0\fR). This is the default. Use \fI\-\-largest\fR and \fI\-\-noremove\fR to alter this behaviour. .IP "\fB\-l, \-\-largest\fR" 4 .IX Item "-l, --largest" When mussort reaches two files with identical names, it will remove (delete) the smallest file and leave the largest in place. .IP "\fB\-n, \-\-noremove\fR" 4 .IX Item "-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. .IP "\fB\-i, \-\-insensitive\fR" 4 .IX Item "-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 \fImight\fR 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 \&\fI\-\-consistent\fR). .Sp You can combine this option with \fI\-\-compilation\fR if you want to. You can not combine \fI\-\-insensitive\fR with \fI\-\-consistent\fR. .IP "\fB\-s, \-\-consistent\fR" 4 .IX Item "-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 \fI\-i\fR, the performance penalty is almost nonexistent. .Sp You can combine this option with \fI\-\-compilation\fR if you want to. Note that \&\fI\-\-compilation\fR changes the directory layout, so a collection sorted without \&\fI\-\-compilation\fR but with \fI\-\-consistent\fR will differ from a collection sorted with both \fI\-\-compilation\fR \fBand\fR \fI\-\-consistent\fR. You can not combine \fI\-\-consistent\fR with \fI\-\-insensitive\fR. .IP "\fB\-a, \-\-allowspecial\fR" 4 .IX Item "-a, --allowspecial" This forces mussort to not strip special characters from file and directory names. .IP "\fB\-c, \-\-compilation\fR" 4 .IX Item "-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 \fI\s-1ALBUM/FILENAME\s0\fR instead of \&\fI\s-1ARTIST/ALBUM/FILENAME\s0\fR. .Sp 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. .IP "\fB\-\-silentskip\fR" 4 .IX Item "--silentskip" Makes mussort not output messages about files that it skips (those that are skipped are generally badly tagged, or not tagged at all). .IP "\fB\-v, \-\-verbose\fR" 4 .IX Item "-v, --verbose" Increases the verbosity of mussort. Supply twice to further increase verbosity. .Sp 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). .Sp If supplied twice, it will also output information about which file is currently being read. .IP "\fB\-\-quiet\fR" 4 .IX Item "--quiet" Suppresses all status messages (and the terminal title). Errors will still get printed. .IP "\fB\-\-dry\-run\fR" 4 .IX Item "--dry-run" Just output what would be done, without actually doing it. .IP "\fB\-\-no\-cache\fR" 4 .IX Item "--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. .Sp 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. .IP "\fB\-\-refresh\-cache\fR" 4 .IX Item "--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. .IP "\fB\-\-cleancache\fR" 4 .IX Item "--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. .Sp This can be useful in a few cases: .RS 4 .IP "\- If you have deleted or mvoed a large amount of music files that mussort has previously sorted" 4 .IX Item "- If you have deleted or mvoed a large amount of music files that mussort has previously sorted" .PD 0 .IP "\- If you want to save a tiny bit of \s-1HD\s0 space" 4 .IX Item "- If you want to save a tiny bit of HD space" .IP "\- If you want mussort to re-read information from files that previously contained invalid data" 4 .IX Item "- If you want mussort to re-read information from files that previously contained invalid data" .RE .RS 4 .PD .Sp mussort will automatically re-evaluate any expired cache data during runtime, so you are never \fBrequired\fR to run \fI\-\-cleancache\fR. .RE .IP "\fB\-\-cleantree\fR" 4 .IX Item "--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 \fBreaddir()\fR operations, and should only be done if you notice a lot of empty directories in your music tree and want them cleaned up. .Sp 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. .SH "DEPENDENCIES" .IX Header "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. .PP It needs: .IP "For \s-1MP3:\s0 id3v2 (best), id3info from id3lib, or Audio::File" 4 .IX Item "For MP3: id3v2 (best), id3info from id3lib, or Audio::File" .PD 0 .IP "For Vorbis: Ogg::Vorbis::Header::PurePerl (best), ogginfo from vorbis-tools, or Audio::File" 4 .IX Item "For Vorbis: Ogg::Vorbis::Header::PurePerl (best), ogginfo from vorbis-tools, or Audio::File" .IP "For \s-1FLAC:\s0 Audio::File (best) or metaflac" 4 .IX Item "For FLAC: Audio::File (best) or metaflac" .PD .SH "FILES" .IX Header "FILES" .IP "~/.mussort\-cache" 4 .IX Item "~/.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). .SH "BUGS AND LIMITATIONS" .IX Header "BUGS AND LIMITATIONS" If you find a bug, please report it at . .SH "INCOMPATIBILITIES" .IX Header "INCOMPATIBILITIES" None known. .SH "AUTHOR" .IX Header "AUTHOR" \&\fBmussort\fR is written by Eskild Hustvedt \fI .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright (C) Eskild Hustvedt 2007, 2008, 2009, 2010, 2011 .PP This is free software; see the source for copying conditions. There is \s-1NO\s0 warranty; not even for \s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0