How to update the Cmus music library

Published:
Updated:
Author:
License:
CC BY-SA 4.0

Explaination of how to update the Cmus music library manually using commands like :add, :update-cache, and :clear, or automatically via a configuration file or a custom shell script with a key binding.

Introduction #

Cmus is a lightweight, terminal-based music player for Unix-like systems that supports various audio formats and powerful library management features. Users may have trouble updating the library due to incorrect music directory paths, outdated caches, missing permissions, or forgetting to run commands like :add or :update-cache.
For more useful commands, see the Cmus cheat sheet.

This article explains how to update the Cmus music library so that Cmus reloads and updates the database with newly added music.

manually Refresh Cmus library #

To update (reload/refresh) the Cmus music library, use the following commands:

Add a Music Folder #

The following Cmus command scans the specified directory and adds its music files to the library.

:add /path/to/your/music

Rescan the Library #

The following Cmus command rescans the existing music library for changes, updating file metadata and detecting new or modified tracks.

:update-cache

Remove Missing Files #

To remove missing files, run the following two Cmus commands.

:clear
:add /path/to/your/music

Breakdown:

Automatically update Cmus library #

There are two ways to update the Cmus library automatically. One is via a config file and the other is using a shell script. Neither option is particularly elegant, but it works.

Config file #

To regenerate the Cmus library every time you start Cmus - which is equivalent to an update/refresh/reload - you can simply add the following command sequence to the Cmus config file (~/.config/cmus/rc).

clear
add ~/Music/
add /path/to/your/music
update-cache -f

Breakdown:

This sequence clears the library, adds files from the specified directory, and forces a metadata refresh.

Script #

If you do not want to regenerate the Cmus library every time you start Cmus, but still want to rebuild the database with a key, you can simply call a script with a key in Cmus. Just do the following:

  1. Create a Bash script

     #!/bin/bash
    
 # Remove all tracks from Cmus library without deleting any
 # files from the disk.
 cmus-remote -C clear
    
 # Scans the specified directories and adds contained music
 # files to the Cmus library.
 cmus-remote -C "add ~/Music"
 cmus-remote -C "add /path/to/your/music"
    
 # Forces a full rescan of the entire library, refreshing 
 # metadata and checking for changes in the files.
 cmus-remote -C "update-cache -f"

    In my case, I called the file update-cmus-library.sh and I’ve placed it in my ~/Bin directory.

  2. Make the script executable

     chmod +x ~/Bin/update-cmus-library.sh

    Learn more about permissions in Linux.

  3. Bind the update script to u key in Cmus

     :bind -f common u shell ~/Bin/update-cmus-library.sh

    In Cmus, just use shift+Ctrl+v to pase this command. Press Enter and your are done. You can immediately use the u key to update the library.

In Cmus, go to Settings View to check if the binding worked. It should be listed under Keybindings like that: common u shell ~/Bin/update-cmus-library.sh.

Further readings #

Sources and recommended, further resources on the topic:

Jonas Jared Jacek • J15k

Jonas Jared Jacek (J15k)

Jonas works as project manager, web designer, and web developer since 2001. On top of that, he is a Linux system administrator with a broad interest in things related to programming, architecture, and design. See: https://www.j15k.com/

License: How to update the Cmus music library by Jonas Jared Jacek is licensed under CC BY-SA 4.0.

This license requires that reusers give credit to the creator. It allows reusers to distribute, remix, adapt, and build upon the material in any medium or format, for noncommercial purposes only. To give credit, provide a link back to the original source, the author, and the license e.g. like this:

<p xmlns:cc="http://creativecommons.org/ns#" xmlns:dct="http://purl.org/dc/terms/"><a property="dct:title" rel="cc:attributionURL" href="https://www.ditig.com/instructions/how-to-update-cmus-library">How to update the Cmus music library</a> by <a rel="cc:attributionURL dct:creator" property="cc:attributionName" href="https://www.j15k.com/">Jonas Jared Jacek</a> is licensed under <a href="https://creativecommons.org/licenses/by-sa/4.0/" target="_blank" rel="license noopener noreferrer">CC BY-SA 4.0</a>.</p>

For more information see the DITig legal page.

“Good design comes from a deep understanding of the technologies behind the scenes.”

Jeffrey Veen, American designer and design strategistThe Art & Science of Web Design, - IT quotes