mussort(1)

💖 mussort — a manual page, but make it cute 💖

okay so bestie, this is mussort(1), from the section 1 of the manual (you know, the "user commands" section, the main character one 💅). if your music folder is a crime scene, this is the forensics team. let's get into it 🎀

---

✨ NAME ✨

mussort — a simple music file sorting program 🎵🦋

---

🌸 SYNOPSIS 🌸

mussort [OPTIONS] dir1 dir2 ..

---

💜 DESCRIPTION 💜

okay so real talk: this is a simple tool that sorts a music collection. that's the whole vibe. 🌈

it recursively searches a directory for MP3, OGG Vorbis and FLAC files, processing them one by one. then it reads the information from the file and puts them into a newly sorted directory tree, shaped like this:

base_directory/ARTIST/ALBUM/FILENAME

and the files get 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. so like, it's not gonna invent a track number out of thin air, bestie, it's not a liar 😤

if you use --compilation then the sorting will differ for those albums that are detected to be compilation albums — those get sorted as base_directory/ALBUM/FILENAME instead. and mussort will remove directories that end up empty after sorting (it cleans up after itself, iconic behavior fr fr ✨).

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

---

👑 OPTIONS 👑

• -h, --help — displays a short help screen and exits. your lil "what do i do" button 🫶
• --version — displays version information and exits. identity check 💅
• -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. hoarding? no, collecting 💖
• -l, --largest — when mussort reaches two files with identical names, it will remove (delete) the smallest file and leave the largest in place. okay so this one is deleting your files, so like, be aware, no cap 😭
• -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. it's giving "i'm not touching that" 🙈
• -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. slay, efficient queen 👑

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. let the weird little characters live 🦋
• -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. patience, bestie, it's thinking 🧠✨

• --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. it will Not Shut Up and honestly? we love that 💬

• --quiet — suppresses all status messages (and the terminal title). errors will still get printed. quiet but not silent, yk? errors still come through 💀
• --dry-run — just output what would be done, without actually doing it. the "manifesting" option ✨
• --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 subsequent 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. it's a treat, not a chore 💅

• --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. so like, it's thorough. maybe too thorough. 🧹✨

---

🎀 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. resilient king 🫶

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>. we don't gatekeep, we report 👑

---

🌈 INCOMPATIBILITIES 🌈

none known. zero drama. periodt. ✨

---

🌸 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. so like, if it eats your music library, that's between you and the void, bestie 😭 (it won't, probably, but legally speaking: no promises 🫶)

---

okay and that's the whole page!! this one's mussort version 0.4, dated 2021-01-07, and it's the mussort(1) page in all its glory. go sort something, you've got this 💅🎀✨