Repository files navigation

muso is a CLI tool that helps you to keep your music folder sorted. It'sdesigned to be simple and fast, but also powerful and fully automated. Currentlymuso supports MP3, FLAC, OGG, M4A and M4P.

To buildmuso yourself you need at least Rust 1.41. If you aren't goingto install it using a package manager you should buildmuso with featurestandalone activated, for example:

cargo build --features standalone --release

The standalone feature include contents ofservice andconfig in binary, somuso can create these files by itself.

To install from source using cargo (installed bin is in$HOME/.cargo/bin)you can do the following:

cargo install --path. --features standalone

Package is alsoavailable on the AURfor Arch Linux, just install it using your preferred method, for example:

yay -S muso

muso is all about renaming and moving files around, but how it'll decidewhere the new file will reside, or which is going to be its name? Fortunatelyyou can tellmuso how to rename your files with aformat string. Thisstring will build the new name (path) using one or more of the followingplaceholders:

• {artist}: Artist name (Album Artist from tags is preferred, thenArtist).
• {album}: Album name.
• {disc}: Disc number.
• {track}: Track number.
• {title}: Song title.
• {ext}: File extension (e.g.mp3,flac)

As an example, the default format thatmuso will use is the following.

"{artist}/{album}/{track} - {title}.{ext}"

The{disc} and{track} placeholders have the option to fillwith leading zeros, the syntax is{disc:n} or{track:n} wheren is thelength that has to be achieved adding leading zeros. For example, using{disc:2} will produce the following transformations:

• 2 will become02
• 10 will become10

Finally, all of these placeholders (except{ext}) support an optional flag(activated by adding a? before the}, e.g.{artist?},{disc:2?}).Renaming a file that doesn't have an specific tag doesn't fail but leaves emptythat placeholder in the string, however note that there are some rules:

• Directory components cannot be optional (e.g. this is invalid{artist}/{album?}/{title}.{ext})
• File name component must have one required placeholder, apart from{ext} (e.g. this is invalid{artist}/{title?}.{ext})

Note: These rules may be different in the future if I find a better way to fill these "unknowns" (possibly using? for digits andUnknown for strings, or adding the option to provide a custom value).

A format string can be specified foroneshot mode using the-f/--formatoption, or providing it in for eachlibrary in theconfigfile.

We recently talked about libraries, these objects are used in theconfigfile to providemuso settings while it's running inwatcher mode. For example, the default library provided in thedefault config file is described as follows.

[libraries.default]# Specified format that will be used for this libraryformat ='{artist}/{album}/{track} - {title}.{ext}'# Folders that compose this libraryfolders = ['$HOME/Music']# If enabled, the rename will be compatible with exFATexfat-compat =true

They are used to provide different options, to different folders.

muso will search for a config file in the following directories in order:

• $XDG_CONFIG_DIR/muso/config.toml
• $HOME/.config/muso/config.toml

It's also possible to indicate a custom path for config file with the-c/--config option. Config file is primary used when running inwatchermode, but it's also able to provide a defaultformat string for certainfolders while running inoneshot mode. For example, in thedefault configfile the default library specifies a format and a list offolders, if you would runmuso on$HOME/Music without specifying aformat, it'll try to grab it from the config file, if there isn't one thatcorrespond to the folder it'll fallback to thedefault.

muso can be used in two modes:oneshot andwatcher. Both of them havesimilar functionalities, but as the naming suggest they perform it differently.Below we have the output ofmuso --help, which explains each option or flag available

USAGE:    muso [OPTIONS] <SUBCOMMAND>FLAGS:    -h, --help       Prints help information    -V, --version    Prints version informationOPTIONS:    -c, --config <config>    Path to custom config fileSUBCOMMANDS:    copy-service    Copy service file to systemd user config dir    help            Prints this message or the help of the given subcommand(s)    sort            Sort a music directory    watch           Watch libraries and sort added files

By the default,muso will run on the current working dir, but you canprovide your own path as a free argument. Config file is optional in this mode.

In this mode config file is required, and as it's described in section[watch]of thedefault config file, the watcher can be configured.

[watch]every =1# second(s)# Specifies which libraries will be seen by musolibraries = ['default' ]

It's recommended to invoke thewatcher mode using the providedservicefile forsystemd, this way you can runmusoautomatically on boot. Service file should be run on user level (systemctl --user). The easiest way to copy the service file is runningmuso withcopy-service subcommand.

GNU General Public License v3.0

SeeLICENSE to see the full text.