Awesome Open Source
Awesome Open Source


muso is a CLI tool that helps you to keep your music folder sorted. It's designed to be simple and fast, but also powerful and fully automated. Currently muso supports MP3 and FLAC, but in the future it's planned to support most codecs for audio.


To build muso yourself you need at least Rust 1.41. If you aren't going to install it using a package manager you should build muso with feature standalone activated, for example:

cargo build --features standalone --release

The standalone feature include contents of service and config in binary, so muso 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 also available on the AUR for Arch Linux, just install it using your preferred method, for example:

yay -S muso


Format string

muso is all about renaming and moving files around, but how it'll decide where the new file will reside, or which is going to be its name? Fortunately you can tell muso how to rename your files with a format string. This string will build the new name (path) using one or more of the following placeholders:

  • {artist}: Artist name (Album Artist from tags is preferred, then Artist).
  • {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 that muso will use is the following.

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

Additionally, {disc} and {track} placeholders have the option to fill with leading zeros, the syntax is {disc:n} or {track:n} where n is the length that has to be achieved adding leading zeros. For example, using {disc:2} will produce the following transformations:

  • 2 will become 02
  • 10 will become 10

A format string can be specified for oneshot mode using the -f/--format option, or providing it in for each library in the config file.


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

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

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

Config file

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 in watcher mode, but it's also able to provide a default format string for certain folders while running in oneshot mode. For example, in the default config file the default library specifies a format and a list of folders, if you would run muso on $HOME/Music without specifying a format, it'll try to grab it from the config file, if there isn't one that correspond to the folder it'll fallback to the default.


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

    muso [FLAGS] [OPTIONS] [path]

        --copy-service    Copy service file to systemd user config dir, nothing else
    -d, --dryrun          Don't create neither move anything
        --exfat-compat    Maintain names compatible with FAT32
    -h, --help            Prints help information
    -r, --recursive       Search for files recursively
    -V, --version         Prints version information
    -w, --watch           Watch libraries present in config

    -C, --config <config>    Custom config file location
    -f, --format <format>    Custom format string

    <path>    Working path to sort

Note about --copy--service, it'll only copy service file to systemd user config dir, and nothing else. muso won't do it's usual job of sorting and will fail if other flags are provided.


By the default, muso will run on the current working dir, but you can provide 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 the default config file, the watcher can be configured.

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

Systemd service

It's recommended to invoke the watcher mode using the provided service file for systemd, this way you can run muso automatically on boot. Service file should be run on user level (systemd --user). The easiest way to copy the service file is running muso with --copy-service, that's all.


GNU General Public License v3.0

See LICENSE to see the full text.

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
rust (3,519
music (487
media (100
album (27
watcher (25
organizer (14

Find Open Source By Browsing 7,000 Topics Across 59 Categories