CMUS(1)

📦
version 2.12.0 · 4 versions
, in alpine 3.24, arch rolling, debian trixie, nixos 26.05, nixpkgs unstable, ubuntu questing, ubuntu resolute, ubuntu stonking

🎧 cmus(1) — General Commands Manual 🎧

hiii bestie 💖 welcome to the manual for cmus, aka the C* Music Player. it's giving lightweight ncurses excellence and we're gonna go through it together, no cap. ✨

✨ NAME ✨

cmus - C* Music Player 🎶

🚀 SYNOPSIS 🚀

cmus [options]

💫 DESCRIPTION 💫

cmus is a lightweight ncurses music player. It supports various output methods by using dynamically-loaded output plugins. cmus has configurable keybindings and can be controlled externally using cmus-remote(1). Lowkey iconic. 🦋

🎛️ OPTIONS 🎛️

  • --listen ADDR — listen on ADDR (UNIX socket) instead of $CMUS_SOCKET or $XDG_RUNTIME_DIR/cmus-socket. ADDR must be a UNIX socket or host[:port].
WARNING: Using host[:port] is insecure even with a password! It may be on a LAN if you want multiple users to be able to control cmus. Never expose cmus to the internet. 🚨
NOTE: Don't use this option to run multiple instances as the same user. Doing so would corrupt the track metadata cache. 💀
  • --plugins — list available plugins and exit. 💅
  • --show-cursor — always display the cursor. This is useful for screen readers. 🫶
  • --help — display usage information and exit. ✨
  • --version — display version information and exit. 🌈

👀 VIEWS 👀

There are 7 views in cmus. Press keys 1-7 to change active view. It's giving tabs but cuter. 💖

  • Library view (1) — displays all tracks in the library. Tracks are sorted and displayed in a tree grouped by artist/album. Artist sorting is done alphabetically. Albums are sorted by year. 📚
  • Sorted library view (2) — displays the same content as view 1, but as a simple list automatically sorted by user criteria. ✨
  • Playlist view (3) — displays editable playlists with optional sorting. 🎀
  • Play Queue view (4) — displays upcoming tracks. These tracks are played before anything else (i.e. the playlist or library). Once the queue is empty, playback will resume from the last position in the library. ⏭️
  • Browser (5) — displays the directory browser. In this view, music from the filesystem can be added to the library, active playlist, or queue. 📁
  • Filters view (6) — lists user-defined filters. 🧚
  • Settings view (7) — lists keybindings, unbound commands and options. Remove bindings with D or del, change bindings and variables with enter, and toggle variables with space. ⚙️

⌨️ COMMAND LINE ⌨️

Everything in cmus is implemented as commands which can be typed at the command line or bound to a key. To enter command mode type :. To execute a command, press ENTER, and to cancel, press ESC or CTRL-C. Use up/down arrows to browse the command history. Use TAB to complete commands and parameters. You don't need to type the full command name if it is unambiguous (no other commands starting with the same characters). Periodt. 💅

Examples:

# add files, short for ':add ~/music'
:a ~/music

# change output plugin
:set output_plugin=oss

# start playing
# you could just press 'x' which is the default
# binding for this command
:player-play

# clear current view (library, playlist or play queue)
:clear

🔍 SEARCHING 🔍

Search mode works like the command mode. To enter search mode, press / and type the query then press ENTER. Press n to move to the next result or N for the previous one. Type ? to search backwards. 🔎

In views 1-4 the query is matched against the artist, album and title tags. Type //WORDS or ??WORDS to search only artists/albums in view 1 and only titles in views 2-4. If the file doesn't have tags, words are compared to the filename excluding the path. 👑

Searching also works in views 5-7. ✨

📝 PLAYLIST EDITING 📝

🎯 Selecting Tracks 🎯

Editing commands affect the currently marked tracks. If there are no marked tracks, the currently selected track (or selected artist/album in view 1) is used. 🫶

To mark the selected track, press SPACE. Marked tracks appear with a gray background. You can only mark tracks in the list views (2-4). 💖

📋 Copying Tracks Between Views 📋

You can copy marked or selected tracks in views 1-5. ✨

  • a — copy tracks to the library (1-2)
  • y — copy tracks to the marked playlist (3)
  • e — append tracks to the play queue (4)
  • E — prepend tracks to the play queue (4)

🚚 Moving Tracks 🚚

In views 2-4, tracks can be moved within the list. Note that moving is disabled if the view is auto-sorted (see lib_sort and pl_sort options). 🛑

Pressing p moves marked tracks to the position immediately after the selected track. P moves them to the position immediately before the selected track. If there are no marked tracks, the selected track is moved down (p) or up (P). 💫

Note that changing active filters in view 2 reloads it, losing any changes made to the track order. 😭

🗑️ Removing Tracks 🗑️

Press D or delete to remove the marked or selected tracks in the current view (1-4). The tracks will be removed immediately from the view without asking for confirmation. In the browser and filters views, the same keys are used to remove a file or filter after asking for confirmation. 💀

📊 STATUS LINE 📊

The right hand side of the status line (second row from the bottom, black text on a grey background) consists of the following fields:

aaa_mode & play_sorted & play_library | volume | continue follow repeat shuffle
NOTE: aaa_mode and play_sorted will be only displayed if play_library is true because these are meaningless when playing the playlists (view 3). 👀

Pressing m, o, M, C, r and s should make it easier to understand what these fields mean. 💅

See the CONFIGURATION OPTIONS section for more information about these options. ✨

🎹 KEYBINDINGS 🎹

Here's list of default keybindings. To change them, see the unbind and bind commands in the COMMANDS section. 🫶

🎵 Common: Playback 🎵

  • b — player-next
  • c — player-pause
  • x — player-play
  • z — player-prev
  • v — player-stop
  • B — player-next-album
  • Z — player-prev-album
  • ] — vol +0 +1%
  • [ — vol +1% +0
  • + — vol +10%
  • = — vol +10%
  • } — vol -0 -1%
  • { — vol -1% -0
  • - — vol -10%
  • , — seek -1m
  • . — seek +1m
  • h — seek -5
  • l — seek +5
  • left — seek -5
  • right — seek +5
  • mlb_click_bar — player-pause
  • mlb_click_bar_right — player-pause
  • mouse_scroll_up_bar — seek +5
  • mouse_scroll_down_bar — seek -5
  • mouse_scroll_up_bar_right — vol +1%
  • mouse_scroll_down_bar_right — vol -1%

🔁 Common: Setting Toggles 🔁

  • m — toggle aaa_mode
  • C — toggle continue
  • M — toggle play_library
  • o — toggle play_sorted
  • r — toggle repeat
  • ^R — toggle repeat_current
  • t — toggle show_remaining_time
  • s — toggle shuffle
  • f — toggle follow

💬 Common: Commands 💬

  • q — quit -i
  • ^C — echo Type :quit<enter> to exit cmus.
  • I — echo {}
  • ! — push shell<space>

🧭 Common: View/Window Navigation 🧭

  • 1 — view tree
  • 2 — view sorted
  • 3 — view playlist
  • 4 — view queue
  • 5 — view browser
  • 6 — view filters
  • 7 — view settings
  • mouse_scroll_up_title — left-view
  • mouse_scroll_down_title — right-view
  • tab — win-next
  • ^L — refresh

🧚 Common: Navigation 🧚

  • ^Y — win-scroll-up
  • ^E — win-scroll-down
  • ^B — win-page-up
  • ^F — win-page-down
  • ^U — win-half-page-up
  • ^D — win-half-page-down
  • k — win-up
  • j — win-down
  • g — win-top
  • G — win-bottom
  • up — win-up
  • down — win-down
  • home — win-top
  • end — win-bottom
  • page_up — win-page-up
  • page_down — win-page-down
  • mouse_scroll_up — win-up
  • mouse_scroll_down — win-down

✨ Common: Selection ✨

  • i — win-sel-cur
  • enter — win-activate
  • mlb_click_selected — win-activate
  • space — win-toggle
  • D — win-remove
  • delete — win-remove
  • p — win-mv-after
  • P — win-mv-before
  • E — win-add-Q
  • a — win-add-l
  • y — win-add-p
  • e — win-add-q
  • u — update-cache
  • U — win-update-cache

🎛️ Common: Filters 🎛️

  • / — search-start
  • ? — search-b-start
  • n — search-next
  • N — search-prev
  • F — push filter<space>
  • L — push live-filter<space>

📁 File Browser 📁

  • space — win-activate
  • backspace — browser-up
  • i — toggle show_hidden
  • u — win-update

✨ LIBRARY VIEW SORTING ✨

okay bestie so the library view (the tree-like one, NOT the sorted library view which is configured with lib_sort — see CONFIGURATION OPTIONS) is sorted automatically using tags from the audio files. no cap.

💖 Note: Albums which feature various artists (e.g. samplers or compilations) are treated specially. If an album artist tag or the ID3v2 TPE2 frame is set, it will be used instead of the real artist name. Otherwise, cmus determines if the album is a compilation (if albumartist or artist are set to Various Artists, Various, VA, or V/A; or if compilation or partofacompilation are set to a truthy value; or if the ID3v2 TCMP frame is set). If so, the artist is named <Various Artists>.
🦋 Note: If the filename is a URL, the artist/album tags are set to <Stream>. If it is a file, cmus sets the artist and/or album tags to <No Name> if they are not already set. These names will be treated the same way as other names for sorting.

In general, three levels of sorting are used in the library view: the artist name, then the album, and finally the track itself.

First, cmus sorts alphanumerically by the value of the artist tag. If a special sorting tag is available, its value will be used instead.

Next, cmus sorts by the album. Tracks are grouped by the album name, and the groups are sorted by the date of the first track, then alphanumerically by the name of the album. If the date header is not set, the album will be placed on top of the list.

Finally, each album is sorted by the track discnumber, tracknumber, then filename (not the track name).

🎮 COMMANDS 🎮

This section describes cmus' commands, which can be bound to keys and mouse events, put in configuration files, executed in command mode, or passed to cmus-remote.

Optional parameters are in [brackets], required parameters in <angle brackets> and default key bindings are (parenthesized).

  • add [-l] [-p] [-q] [-Q] <file|dir|url|playlist> — Adds file/dir/url/playlist to the specified view or the current view.
    • -l — add to library
    • -p — add to playlist
    • -q — add play queue
    • -Q — prepend to play queue

Supported files are based on the loaded input plugins.

Supported URLs: Shoutcast (http://...), CDDA (cdda://...).

Supported playlist types: plain, .m3u, .pls.

  • bind [-f] <context> <key> <command> — Adds a key binding.
    • -f — overwrite existing binding

Valid contexts: common (i.e. all views), library (1-2), playlist (3), queue (4), browser (5), filters (6)

There's one context for each view. Common is a special context on which bound keys work in every view.

You can override specific keys in common context for a view. For example i selects the current track in views 1-3 but in browser it is overridden to toggle showing of hidden files.

When setting custom bindings in $XDG_CONFIG_HOME/cmus/rc, it is recommended to use the -f option, or else bind may fail due to an existing binding in the autosave or system-level config files.

💡 Hint: You can press tab from command mode to expand contexts, keys, and commands.
  • browser-up (backspace) — Navigates the browser view to the parent directory (5). This command only makes sense to be bound to the browser key context although it's possible to use this even if browser view is not active.
  • cd [directory] — Changes the current working directory. Also changes the directory displayed in the browser view.
  • clear [-l] [-p] [-q] — Removes all tracks from a single view.
    • -l — clear library
    • -p — clear playlist
    • -q — clear play queue

If a view is not specified, the current view is used.

  • colorscheme <name> — Changes the color scheme. Color schemes are found in /usr/share/cmus/ or $XDG_CONFIG_HOME/cmus/ and have the extension .theme.
  • echo <arg>... — Displays the arguments on the command line.
    • {} — it is replaced with file name of the first selected track.
  • factivate <user-defined-filter>... — Selects and activates the given user defined filters (displayed in the filters view). Filter names are separated by spaces. This command is mostly useful when bound to a key to change active filters quickly. If no arguments are provided, all filters are deactivated.
    • Prefix a filter name with ! to negate it.
  • filter <filter-expression> — Temporarily filters a library view. The filter is not saved (use fset and factivate for that).
  • fset <name>=<filter-expression> — Defines or replaces an existing filter and adds it to the filters view (6).
  • help — Shows information about help files.
  • invert — Inverts the marking of tracks in playlist and queue views. See mark and unmark.
  • live-filter <simple-filter-expression|short-filter-expression> — Like filter, but uses simple filters and shows a preview as you type. It persists even after leaving command mode.
  • load [-l] <playlist> — Loads a playlist to a view.
    • -l — load to library views

If a view is not specified, the current view is used, which must be 1-2.

  • lqueue [NUM] — Queues NUM (default 1) random albums from the library. Also see tqueue.
  • mark <filter-expression> — Marks tracks in playlist and queue view using a filter expression.
  • mute — Toggles mute for the sound output.
  • pl-create <name> — Creates a new playlist.
  • pl-delete [-a] <name> — Deletes the playlist with the given name.
    • -a — Deletes all playlists
  • pl-export <filename> — Exports the currently selected playlist. The file will be overwritten if it exists.
  • pl-import [filename] — Imports a playlist into the playlist view. The argument can be omitted in the file browser view.
  • pl-rename <name> — Renames the selected playlist.
  • player-next (b) — Skips to the next track.
  • player-next-album (B) — Skips to the next album. If shuffle=tracks or a playlist is active, skips to the next track.
  • player-pause (c) — Toggles pause.
  • player-pause-playback — Pauses if currently playing.
  • player-play [filename] (x) — Plays the given track, or, if none is specified, [re]plays the current track from the beginning.
  • player-prev (z) — Skips to the previous track.
  • player-prev-album (Z) — Skips to the previous album. If shuffle=tracks or a playlist is active, skips to the previous track.
  • player-stop (v) — Stops playback.
  • prev-view — Goes to the previously used view.
  • left-view [-n] — Goes to the to view to the left of current one (e.g. view 4 -> view 3)
    • -n — no cycle back to end when reaching the first view
  • right-view [-n] — Goes to view to the right of current one (e.g. view 3 -> view 4).
    • -n — no cycle back to start when reaching the last view
  • push [text] — Enters command mode with the command line pre-set to text. Example:
bind common w push filter artist=

Text can contain spaces, which will be used as-is (e.g. trailing spaces will be preserved). If no text is given, it defaults to a blank command line.

This command can only be used from a keybinding.

  • pwd — Prints the current working directory.
  • quit [-i] (q, :wq) — Exits cmus.
    • -i — ask before exiting
  • raise-vte — Raises the virtual terminal emulator window. Only works within a X session.
  • rand — Randomizes (shuffles) the tracks in the library, playlist or queue view.
  • refresh (^L) — Redraws the terminal window.
  • reshuffle — Reshuffles the shuffle lists for both library and playlist views.
  • run <command> — Runs a command for the marked tracks OR the selected one if none marked.

By default file names are appended to the command. If the command contains {} it is replaced with list of filenames.

Note: In view 1 you can run a command for all files in the selected album or artist.
  • save [-e] [-l] [-L] [-p] [-q] [file] (:w) — Saves the contents of a view to a playlist file. In extended mode (-e), also saves track metadata.
    • -l — save library views
    • -L — save filtered library views
    • -p — save playlist view
    • -q — save queue view

If no view is specified, the current one is used.

If no filename given the old filename is used. "-" outputs to stdout (works only remotely).

  • search-b-start — Enters backwards search mode. Cannot be used directly from command mode.

See search-start.

  • search-next (n) — If there is an active search, goes to the next match in the current view. See SEARCHING above.
  • search-prev (N) — If there is an active search, goes to the previous match in the current view. See SEARCHING above.
  • search-start — Enters search mode. Cannot be used directly from command mode.

This is similar to live-filter, except it is temporary and only selects the current match rather than filtering the entire view.

  • seek [+-](<num>[mh] | [HH:]MM:SS) — Seeks to an absolute or relative position, which can be given in seconds, minutes (m), hours (h) or HH:MM:SS format where HH: is optional.

Seek 1 minute backward

:seek -1m

Seek 5 seconds forward

:seek +5

Seek to absolute position 1h

:seek 1h

Seek 90 seconds forward

:seek +1:30
  • set <option>=<value> — Sets the value of an option. See OPTIONS.
  • set <option> — Display option value. Vim compatible set <option>? is also supported.
  • shell <command> — Executes a command via /bin/sh -c.
  • showbind <context> <key> — Shows a key binding.
  • source <filename> — Reads and executes commands from <filename>.
  • toggle <option> — Toggles the value of a toggle-able option (all booleans and the options shuffle, aaa_mode, and replaygain).
  • tqueue [NUM] — Queues NUM (default 1) random tracks from the library. See also lqueue.
  • unbind [-f] <context> <key> — Removes a key binding. Use tab to cycle through bound keys.
  • -f — don't throw an error if the binding is not known 💅 (continuing the option list from up top, bestie)
  • unmark — unmarks literally all the tracks (peep mark for the receipts) ✨
  • update-cache [-f] — refreshes the track metadata cache ($XDG_CONFIG_HOME/cmus/cache). By default it only touches deletions or files whose modification time changed, no cap.
    • -f — update everything. Same energy as quit, then rm -f $XDG_CONFIG_HOME/cmus/cache, then start cmus 🔥
  • version — prints the version info. that's it, that's the command 🎀
  • view <name or 1-7> — switches the active view.
Do not use this in $XDG_CONFIG_HOME/cmus/rc to change the starting view. Set the start_view option instead, bestie, I'm begging 🫶
  • vol [+-]NUM[%] [[+-]NUM[%]] — changes the volume.
    • If you hand it a single argument, both channels get changed. Otherwise the first value is for the left channel and the second is for the right one.
    • To bump it up or down, prefix the value with - or + — otherwise the value is treated as an absolute volume.
    • Both absolute and relative values can be given as percentage units (suffix %) or as internal values (hardware may have volume in range 0-31, for example).
  • w — see quit. Intended for use while you're in command mode.
  • win-activate (bound to enter) — in views 1-3 it plays the selected track. In view 5 it starts the selected file or changes into the selected directory. In view 6 it activates the selected filters. In the settings view (7) it changes a binding or a variable. ✨
  • win-add-l [-n] (bound to a) — adds the currently marked or selected track(s) (views 3-4), or the currently selected file/directory (view 5), to the library. It's analogous to :add -l.
    • -n — don't move the selection to the next item.
  • win-add-p [-n] (bound to y) — adds the currently marked or selected track(s) (views 1-2, 4), or the currently selected file or directory (view 5), to the marked playlist. Analogous to :add -p.
    • -n — don't move the selection to the next item.
  • win-add-Q [-n] (bound to E) — prepends the currently marked or selected track(s) (views 1-3), or the currently selected file or directory (view 5), to the play queue. Analogous to :add -Q.
    • -n — don't move the selection to the next item.
  • win-add-q [-n] (bound to e) — adds the currently marked or selected track(s) (views 1-3), or the currently selected file or directory (view 5), to the play queue. Analogous to :add -q.
    • -n — don't move the selection to the next item.
  • win-bottom (bound to G, end) — goes to the bottom of the current window 💅
  • win-down [NUM] (bound to j, down) — goes down NUM rows in the current window (default 1).
  • win-half-page-down (bound to ^D) — goes down half a page in the current window.
  • win-half-page-up (bound to ^U) — goes up half a page in the current window.
  • win-mv-after (bound to p) — moves the marked tracks below the selected track. If nothing is selected, it selects the previous track. If no tracks are marked, it moves the selected track up by one. This one works in the playlist and queue views.
  • win-mv-before (bound to P) — moves the marked tracks above the selected track. If nothing is selected, it selects the previous track. If no tracks are marked, it moves the selected track down by one. Also works in the playlist and queue views.
  • win-next (bound to tab) — activates the next window (i.e. tree/list). Only relevant in view 1.
  • win-page-bottom — goes to the bottom of the visible part of the current window.
  • win-page-down (bound to ^F, page_down) — goes down one page in the current window.
  • win-page-middle — goes to the middle of the visible part of the current window.
  • win-page-top — goes to the top of the visible part of the current window.
  • win-page-up (bound to ^B, page_up) — goes up one page in the current window.
  • win-remove (bound to D, delete) — removes the selected entry. For tracks, no confirmation is required, it just goes. But for playlists (view 3), files (view 5), filters (view 6) and bindings (view 7) you must confirm the action first 🙈
  • win-scroll-down (bound to ^E) — scrolls the current window one row downwards.
  • win-scroll-up (bound to ^Y) — scrolls the current window one row upwards.
  • win-sel-cur (bound to i) — selects the current track (position in library or playlist, not necessarily the same as the currently playing track). Works only in views 1-3, does absolutely nothing in the other views 💀
  • win-toggle (bound to space) — expands albums in library view (1), marks tracks in views 2-4, sets the marked playlist in view 3, toggles selection of a filter in view 6, or toggles a variable's value in view 7. multitasking icon behavior fr fr 👑
  • win-top (bound to g, home) — goes to the top of the current window.
  • win-up [NUM] (bound to k, up) — goes up NUM rows in the current window (default 1).
  • win-update (bound to u) — checks the modification time of the files in the library, and updates metadata for changed files. Also removes non-existent files from the library.

It reloads the contents of the directory in the browser view.

Only works in views 1-2 and 5, does nothing in the other views.

  • win-update-cache [-f] — same as update-cache, but only for the marked / selected tracks. Only works in views 1-2, does nothing in other views.
  • wq — see quit. Intended for use from command mode.

🎀 CONFIGURATION OPTIONS 🎀

This section spills all the tea on the configuration options cmus uses, bestie.

You can change these options with the set and toggle commands. Default values are (parenthesized), and the possible values live in [brackets].

  • auto_expand_albums_follow, auto_expand_albums_search, auto_expand_albums_selcur (true) — always expand an artist and select the album when following the currently played track or doing actions like "search" or "go to current track". This option is tightly coupled to the show_all_tracks option. Any auto_expand_albums_* = false implies show_all_tracks = true.
  • auto_hide_playlists_panel (false) — hide the left panel in playlist view. The panel will show as needed when you activate it with win-next (tab).
  • auto_reshuffle (true) — reshuffle a playlist when the end of a shuffled list is reached.
  • aaa_mode (all) [all, artist, album] — defines what tracks should be played in the library view. Not used in the other views.

For example, if it's set to artist, the player behaves like there were only the files of the currently playing artist in the library. it's giving curated vibes ✨

  • altformat_current [Format String] — alternative format string for the line displaying the currently playing track.
Note: if empty, format_current is used instead.
  • altformat_playlist [Format String] — alternative format string for the list views (2-4).
Note: if empty, format_playlist is used instead.
  • altformat_title [Format String] — alternative format string for the terminal title.
Note: not all terminals support changing window title. Note: if empty, format_title is used instead.
  • altformat_trackwin [Format String] — alternative format string for the tree view's (1) track window.
Note: if empty, format_trackwin is used instead.
  • block_key_paste (true) — prevent accidental input by only accepting pasted text in the command line. Only works on terminals which support bracketed paste.
  • buffer_seconds (10) [1-300] — size of the player buffer in seconds.
  • color_cmdline_bg (default) [Color] — command line background color.
  • color_cmdline_fg (default) [Color] — command line foreground color.
  • color_cmdline_attr (default) [Attributes] — command line attributes.
  • color_error (lightred) [Color] — color of error messages displayed on the command line.
  • color_info (lightyellow) [Color] — color of informational messages displayed on the command line.
  • color_separator (blue) [Color] — color of the separator line between windows in view (1).
  • color_statusline_bg (gray) [Color] — status line background color.
  • color_statusline_fg (black) [Color] — status line foreground color.
  • color_statusline_attr (default) [Attributes] — status line attributes.
  • color_statusline_progress_bg (blue) [Color] — status line background color of the progress bar, when enabled.
  • color_statusline_progress_fg (white) [Color] — status line foreground color of the progress bar, when enabled.
  • color_statusline_progress_attr (default) [Attributes] — status line attributes of the progress bar, when enabled.
  • color_titleline_bg (blue) [Color] — background color of the line displaying the currently playing track.
  • color_titleline_fg (white) [Color] — foreground color of the line displaying the currently playing track.
  • color_titleline_attr (default) [Attributes] — attributes of the line displaying the currently playing track.
  • color_win_bg (default) [Color] — window background color.
  • color_win_cur (lightyellow) [Color] — color of the currently playing track.
  • color_win_cur_attr (default) [Attributes] — currently playing track attributes.
  • color_win_cur_sel_bg (blue) [Color] — background color of the selected row which is also the currently playing track, in the active window.
  • color_win_cur_sel_fg (lightyellow) [Color] — foreground color of the selected row which is also the currently playing track, in the active window.
  • color_win_cur_sel_attr (default) [Attributes] — attributes of the selected row which is also the currently playing track, in the active window.
  • color_win_dir (lightblue) [Color] — color of directories in the browser.
  • color_win_fg (default) [Color] — window foreground color.
  • color_win_attr (default) [Attributes] — window attributes.
  • color_win_inactive_cur_sel_bg (gray) [Color] — background color of the selected row which is also the currently playing track, in an inactive window.
  • color_win_inactive_cur_sel_fg (lightyellow) [Color] — foreground color of the selected row which is also the currently playing track, in an inactive window.
  • color_win_inactive_cur_sel_attr (default) [Attributes] — attributes of the selected row which is also the currently playing track, in an inactive window.
  • color_win_inactive_sel_bg (gray) [Color] — background color of the selected row in an inactive window.
  • color_win_inactive_sel_fg (default black) [Color] — the foreground colour of the selected row when that window is not the one you're vibing in.
  • color_win_inactive_sel_attr (default default) [Attributes] — the attributes of the selected row in an inactive window.
  • color_win_sel_bg (default blue) [Color] — background colour of the selected row in the active window.
  • color_win_sel_fg (default white) [Color] — foreground colour of the selected row in the active window.
  • color_win_sel_attr (default default) [Attributes] — attributes of the selected row in the active window.
  • color_win_title_bg (default blue) [Color] — background colour of the window titles (that's the topmost line of the screen, bestie 👑).
  • color_win_title_fg (default white) [Color] — foreground colour of the window titles (topmost line of the screen).
  • color_win_title_attr (default default) [Attributes] — attributes of the window titles (topmost line of the screen).
  • color_trackwin_album_bg (default default) [Color] — background colour of the album row shown in the track window.
  • color_trackwin_album_fg (default default) [Color] — foreground colour of the album row shown in the track window.
  • color_trackwin_album_attr (default bold) [Attributes] — attributes of the album row shown in the track window.
  • confirm_run (default true) — ask for confirmation before executing :run. yes bestie we're double-checking before we do the thing 💅
  • continue (default true) — keep playing after the current track finishes.
  • continue_album (default true) — keep playing the next album after the current album finishes.
  • device (default /dev/cdrom) — the CDDA device file.
  • display_artist_sort_name (default false) — turn this on and the tree view always shows the artist names used for sorting instead of the regular ones (so like "Artist, The" instead of "The Artist"), which makes the artist column look alphabetically sorted. iconic behaviour honestly.
  • follow (default false) — when enabled, always select the currently playing track whenever the track changes. main character tracking energy ✨
  • format_clipped_text [Plain String] — the string used to lead out any text that gets cut off by field limits.
    • Note: the Format String rules are not applied here. A plain string like "..." is what's expected.
  • format_current [Format String] — format string for the line that displays the currently playing track.
  • format_heading_album [Format String] — format string for the track window heading line when an album is selected in the tree.
  • format_heading_artist [Format String] — format string for the track window heading line when an artist is selected in the tree.
  • format_heading_playlist [Format String] — format string for the heading line in the playlist view (3).
  • format_playlist [Format String] — format string for the list views (2-4).
  • format_playlist_va [Format String] — format string for the list views (2-4) when a track is assumed to be part of a compilation (peep LIBRARY VIEW SORTING for the deets).
    • Note: if this is empty, format_playlist gets used instead.
  • format_statusline [Format String] — format string for the status line.
  • format_title [Format String] — format string for the terminal title.
    • Note: not every terminal supports changing the window title. tragic, I know 😭
  • format_trackwin [Format String] — format string for the tree view's (1) track window.
  • format_trackwin_album [Format String] — format string for albums in the tree view's (1) track window.
  • format_trackwin_va [Format String] — format string for the tree view's (1) track window when a track is assumed to be part of a compilation (see LIBRARY VIEW SORTING for details).
    • Note: if this is empty, format_trackwin is used instead.
  • format_treewin [Format String] — format string for the tree view's (1) tree window.
  • format_treewin_artist [Format String] — format string for artists in the tree view's (1) tree window.
  • smart_artist_sort (default true) — turn this on and the tree view sorting straight-up ignores "The" in front of artist names, so artists starting with "The" don't all clump together like a group chat nobody asked for. Real artistsort tags override this option if they're present, periodt.
  • sort_albums_by_name (default false) — in the tree view (1), albums get sorted by name instead of by date.
  • id3_default_charset (default ISO-8859-1) — the default character set to use for ID3v1 and broken ID3v2 tags.
    • Note: this is only used if the tag isn't valid UTF-8.
  • icecast_default_charset (default ISO-8859-1) — the default character set to use for non-UTF-8 icecast stream metadata.
    • Note: this is only used if the metadata isn't valid UTF-8.
  • ignore_duplicates (default false) — ignore duplicates when adding tracks to the library. A track counts as a duplicate if it has a matching artist, album, disc number, track number, and track name. all five, no shortcuts 💀
  • lib_add_filter [Filter] — apply a filter when adding files to the library. See FILTERS.
  • lib_sort (default artist album discnumber tracknumber title filename) [Sort Keys] — the sort keys for the sorted library view (2).
  • mouse (default false) — enable mouse support.
    • Note: mouse wheel scrolling can lag if cmus was compiled with an old version of ncurses. 🐌
  • mpris (default true) — enable MPRIS support. See D-Bus Interface (MPRIS).
    • Note: this flag does absolutely nothing if cmus was compiled without MPRIS support.
  • output_plugin [roar, pulse, alsa, arts, oss, sndio, sun, coreaudio, aaudio] — the name of the output plugin.
  • passwd [password] — set the password for TCP/IP connections. It's required if you're listening on host:port. No effect at all if you're listening on a UNIX socket. Used in conjunction with --listen.
  • pause_on_output_change (default false) — pauses playback when the audio output changes.
    • Supported output plugins: pulse, aaudio.
  • pl_env_vars — a comma separated list of environment variables to substitute when saving library/playlist files. The paths have to be absolute for this to take effect. See Library Environment Variables.
    • Note: this option won't fully take effect until cmus has been restarted. 🙈
  • pl_sort (default empty) [Sort Keys] — sort keys for the playlist view (3). An empty value disables sorting and lets you manually move tracks around.
  • play_library (default true) — play tracks from the library instead of the playlist.
  • play_sorted (default false) — play tracks from the library in the sorted view (2) order instead of the tree view (1) order. Only used when play_library is true.
  • progress_bar (default line) [disabled, line, shuttle, color, color_shuttle] — draw a bar in the status line showing your current progression through a track. slay ✨
  • repeat (default false) — repeat after all tracks have played.
  • repeat_current (default false) — repeat the current track forever. and ever. and ever. 💀
  • replaygain (default disabled) [track, album, track-preferred, album-preferred, smart] — enable Replay Gain. The smart setting behaves like track-preferred when shuffle is on, or the queue is active, or when you're playing from a playlist. Otherwise it behaves like album-preferred.
  • replaygain_limit (default true) — use replay gain limiting when clipping.
  • replaygain_preamp (default 0.0) — replay gain preamplification in decibels.
  • resume (default false) — resume playback on startup.
  • rewind_offset (default 5) [-1-9999] — if the position of the current track is smaller than rewind_offset, player_prev jumps to the previous track. Otherwise, player_prev jumps to the beginning of the current track. If rewind_offset=-1, player_prev always jumps to the previous track.
  • scroll_offset (default 2) [0-9999] — the minimal number of screen lines to keep above and below the cursor.
  • search_resets_position (default true) — starts searches at the beginning of the current view rather than at the current item.
  • show_all_tracks (default true) — display all tracks of the artist when the artist is selected in the tree view. This option is tightly coupled to the auto_expand_albums_\ options. "show_all_tracks = false" implies "auto_expand_albums_* = true".
  • show_hidden (default false) — display hidden files in the browser.
  • show_current_bitrate (default false) — display the current bitrate in the status lines.
  • show_playback_position (default true) — display elapsed (or remaining) time in the status line. You can disable this to, like, not trigger tmux's activity monitor for example.
  • show_remaining_time (default false) — display remaining time instead of elapsed time.
  • shuffle (default off) [off, tracks, albums] — the shuffle behaviour, bestie:
    • off — play all tracks in order. See also lib_sort and pl_sort.
    • tracks — play all tracks in the library or playlist in a shuffled order.
    • albums — play each library album to completion before shuffling to the first track of another library album. In playlists this option falls back to tracks behaviour.
    • Filters and aaa_mode can be used to limit the items available for play. Note that shuffle=albums will have no effect with aaa_mode=album.
  • skip_track_info (default false) — don't load metadata when adding tracks. Super useful when you're on a network file system and have a huge amount of files. Tags can be loaded using update-cache or win-update-cache commands.
  • softvol (default false) — use software volume control.
    • Note: you should probably set this to false when using ao as output_plugin to output to wav files.
  • softvol_state (default 100 100) — used to save the left and right channel values for software volume control. Two integers in range 0..100 separated by a space. This option isn't usually changed directly since the vol command does the same thing if softvol is true.
  • start_view (default tree) [tree, sorted, playlist, queue, browser, filters, settings] — specify the view that gets shown when cmus starts.
  • status_display_program (default empty) [command] — this command, if set, is run for every status change. You can use it to display the currently playing track on your desktop background or a panel, for example. See /usr/share/doc/cmus/examples/cmus-status-display.
  • stop_after_queue (default false) — stop playback when the end of the play queue is reached.
  • time_show_leading_zero (default true) — pad durations of less than 10 minutes with a leading 0.
  • tree_width_percent (default 33) [1-100] — percentage of the window width to use for the left pane.
  • tree_width_max (default 0) [0-9999] — restrict the size calculated from tree_width_percent. 0 disables this option.

This affects the tree in the library view and the playlist list in the playlist view.

Note that this value will be further constrained by the window width and/or the minimum tree size.

For example, to set a fixed size of 60 columns:

set tree_width_percent=100
set tree_width_max=60

Or, to be 33% wide, but at most 60 columns:

set tree_width_percent=33
set tree_width_max=60

Or, to always be 33% wide where possible (the default behavior):

set tree_width_percent=33
set tree_width_max=0
  • wrap_search (true) — decides whether your search loops back around when it hits the end. True means it wraps, bestie. 🔄

🎨 Colors

A color is just an integer, and it lives in the range -1..255. That's it, that's the whole vibe.

Here are the color names you're allowed to use, and honestly they're iconic:

  • Terminal's default color, -1 — default
  • Fg & bg, 0..7 — black, red, green, yellow, blue, magenta, cyan, gray
  • Fg, 8..15 — darkgray, lightred, lightgreen, lightyellow, lightblue, lightmagenta, lightcyan, white

💅 Attributes

Attributes is a little set of names that goes "standout|bold", okay? Here's the whole roster:

  • default — does absolutely nothing. But if you put it next to other attributes, then the other attributes get used instead. Not me being mysterious, that's just the rule. 🙈
  • standout — makes the text, you know, stand out.
  • bold — makes the text bold.
  • reverse — flips your text colors, chaos mode.
  • underline — underlines the text.
  • italic — makes the text italic. Heads up bestie, this one is not supported on all ncurses versions. 😭
  • blink — makes the text blink. Very 2003 of it.

🌈 Format Strings

Format strings are what control how tracks get displayed in the library, playlist and play queue views. Main character behavior for your columns. ✨

Note: the altformat_* options are used when there are no tags available. iykyk.

Special Keys

  • %a — same as %{artist}
  • %A — same as %{albumartist}
  • %l — same as %{album}
  • %D — same as %{discnumber}
  • %T — same as %{totaldiscs}
  • %n — same as %{tracknumber}
  • %X — same as %{play_count}
  • %t — same as %{title}
  • %g — same as %{genre}
  • %c — same as %{comment}
  • %y — same as %{date}
  • %d — same as %{duration}
  • %f — same as %{path}
  • %F — same as %{filename}
  • %{albumduration}
  • %{originaldate}
  • %{maxdate}
  • %{bpm}
  • %{bitrate}
  • %{codec}
  • %{codec_profile}
  • %{rg_track_gain}
  • %{rg_track_peak}
  • %{rg_album_gain}
  • %{rg_album_peak}
  • %{arranger}
  • %{composer}
  • %{conductor}
  • %{lyricist}
  • %{performer}
  • %{remixer}
  • %{label}
  • %{publisher}
  • %{work}
  • %{opus}
  • %{partnumber}
  • %{part}
  • %{subtitle}
  • %{media}
  • %! — everything before this is lower importance and may get shortened if needed. Use it at most once. 🫶
  • %= — start align right. Also at most once.
  • %% — a literal %
  • %? — a literal ?

You can use printf style formatting — width, alignment, padding, all of it. And as an extension, the width can have a %-suffix so you can specify a percentage of the terminal width. Obsessed. 💖

To see the current value of an option, type :set option=<TAB>.

Note: with %{bitrate} you'll have to append the unit yourself, as shown in the example below. Not us forgetting it, it's a you thing. 🙈

You can use the conditional operator %{?CONDITION?A[?B]}. CONDITION has the same syntax as filters — except for unsupported short and simple expressions, and supported keys comparison (e.g. artist=albumartist). Its keys are:

  • format strings' special keys
  • configuration options
  • keyword stream [boolean] — returns true if the track is a stream
  • keyword va [boolean] — returns true if the track's album is a compilation

The Else part can be skipped entirely. A and B can contain string literals wrapped in " or '. And A and B can be empty. No pressure.

Examples, because a demo just hits different:

:set format_trackwin= %02n. %t %{?y?(%y)}%= %d
:set format_current= %n. %-30t %40F (%y)%= %d
:set format_current= %a - %l%! - %02n. %t%= %{bitrate}Kbps %g %y
:set format_playlist= %f%= %6{rg_track_gain} dB  %8{rg_track_peak}
:set format_playlist= %-25%a %-15%l %3n. %t%= %y %d

🔤 Sort Keys

The sort option (lib_sort, pl_sort) value is a space separated list of the following sort keys:

  • artist, album, title, tracknumber, play_count, discnumber, date, originaldate, genre, comment, albumartist, filename, filemtime, bpm, bitrate, codec, media, codec_profile, rg_track_gain, rg_track_peak, rg_album_gain, rg_album_peak
Note: slapping a - in front of the key reverses the sort order. Little minus, big power. 🔥

🔌 PLUGIN OPTIONS

  • dsp.alsa.device — PCM device for the ALSA plugin, usually "default".
  • mixer.alsa.channel — mixer channel for the ALSA Plugin, usually "pcm", "master" or "headphone". To see all the possible values, run "alsamixer" or "amixer".
  • mixer.alsa.device — mixer device for the ALSA plugin, usually "default".
  • mixer.pulse.restore_volume — restore the volume at startup using PulseAudio. Otherwise, cmus sets the volume to 100%, which does not mix well with the "flat volumes" feature of PA. Defaults to "1"; set it to "0" to turn it off.
  • dsp.ao.buffer_size — the audio buffer size; defaults to 16kB, but you may wanna try bigger values if you're getting buffer under-runs. 😭
  • dsp.ao.device_interface — device interface for the libao plugin, so you can request a specific playback device/sink/output. The name will be in a format determined by the specific driver backend.
  • dsp.ao.driver — output driver for the libao plugin. Example values: "alsa09", "esd", "irix", "oss", "sun", "aixs", "wav".
Note: of the file output drivers, only "wav" is supported.
  • dsp.ao.wav_counter — the counter used for making the filename. Only used if dsp.ao.driver is "wav". For example, if this is 1 and dsp.ao.wav_dir is "/home/user", then PCM data gets outputted to "/home/user/01.wav". This counter increments every time playback is stopped.
Note: you probably want to set continue to false (press C), otherwise playback is not stopped between tracks and all PCM data gets outputted to one wav file (useful if you want to join files). Also unsetting shuffle and repeat might be a good idea.
  • dsp.ao.wav_dir — output directory for the libao plugin; defaults to the home directory. Only used if dsp.ao.driver is "wav".
  • dsp.coreaudio.device — device for Core Audio output. Leave it empty for default.
  • dsp.coreaudio.enable_hog_mode — set hog mode for the device. The default value is false.
  • dsp.coreaudio.sync_sample_rate — synchronize the device sample rate with the player, so no interpolation gets applied to the stream.
  • dsp.jack.server_name — connect to jackd with this name. Leave it empty for default.
  • dsp.jack.resampling_quality — the re-sampling quality. 0 is low quality but fast, 1 is medium quality, 2 (default) is high quality but more CPU intensive. This option is only available if cmus was compiled with libsamplerate support.
  • dsp.aaudio.performance_mode (power_saving) [power_saving, none] — set the requested performance mode. If "power_saving", battery life is prioritized over low latency. If "none", battery life is balanced with low latency.

This option requires restarting cmus. 🔁

  • dsp.aaudio.allowed_capture (all) [all, system, none] — specify whether the audio may or may not be captured by other apps or the system.

This option is only supported on Android 10+ (API 29) and requires restarting cmus.

  • dsp.aaudio.sharing_mode (shared) [shared, exclusive] — request a mode for sharing the device. This is done on a best-effort basis, so the requested sharing mode may not actually be available. 💀

This option requires restarting cmus.

  • dsp.aaudio.disable_spatialization (false) — if true, disables Android's built-in audio spatializer even if it's enabled for the current audio output. Note that spatialization only applies to audio with at least 4 channels. See https://developer.android.com/media/grow/spatial-audio for more details.

This option is only supported on Android 12L+ (API 32) and requires restarting cmus.

  • input.cdio.cddb_url — CDDB URL (default: freedb.freedb.org:8880). Uses HTTP if prefixed with "http://" (e.g.: http://freedb.musicbrainz.org:80/~cddb/cddb.cgi). Set it to an empty string to disable CDDB lookup completely.
  • input.*.priority — sets the priority of the input plugin. If multiple plugins can play a file, the plugin with the higher priority gets chosen. And if the priority is 0, the plugin is disabled.
  • dsp.oss.device — PCM device for the OSS plugin, usually /dev/dsp.
  • mixer.oss.channel — mixer channel for the OSS Plugin, "pcm" or "master".
  • mixer.oss.device — mixer device for the OSS plugin, usually /dev/mixer.
  • dsp.roar.server — address of the RoarAudio server. Defaults to internal defaults. Can be a UNIX, TCP/IP or DECnet address.
  • dsp.roar.role [music, background_music, ...] — role for the stream. May be used by the server to apply additional defaults.
  • dsp.sun.device — PCM device for the Sun plugin, usually /dev/audio.
  • mixer.sun.channel — mixer channel for the Sun Plugin, usually "master".
  • mixer.sun.device — mixer device for the Sun plugin, usually /dev/mixer.

💿 PLAYING AUDIO DISCS

If the cdio input plugin is enabled, you can play CDs and CD images by setting the device option to a device file (e.g. /dev/cdrom) or an image file (e.g. ~/cd.cue). Then you add a new track using the CDDA URL scheme:

:add cdda://2

To add the entire disc, use cdda:// (no track number). Quick heads up though — this only works for audio discs, not images. Adding track ranges is also possible: cdda://1-3.

To add images without changing the device option, just include the image path right in the URL:

:add cdda:///path/to/cd.cue/2-5

The metadata gets read from CD-Text, and if that's not available, it's looked up from a CDDB server (see input.cdio.cddb_url). Slay. 👑

✨ FILTERS ✨

okay bestie, filters are literally the vibe check for your library views (1 & 2). They do NOT change the actual library content, i.e. the :save command will still save all tracks to playlist file whether they are visible or not. no cap.

💅 Types

There are three types of filter expressions, each offering more expressiveness:

  • simple — e.g. beatles
  • short — e.g. ~a beatles (!~y1960-1965 | ~d>600)
  • long — e.g. artist="*beatles*"&album="R*"

Simple expressions are only available using live-filter. For other filter commands the type is auto-detected, so both short and long expressions can be used.

Long expressions are lists of built-in filters or user defined filters separated with & (and) or | (or). Parentheses can be used to group subexpressions and ! negates the result of the expression following it. The same is true for short expressions, but they can only consist of built-in filters. Also, (and)-grouping is done implicitly.

🌸 Strings

  • long — filename, artist, albumartist, album, title, genre, comment, codec, codec_profile, media — Comparators: = and != (not equal)
  • short — ~f, ~a, ~A, ~l, ~t, ~g, ~c — Comparators: none

🔢 Integers

  • long — discnumber, tracknumber, date (year), originaldate (year), duration (seconds), bitrate — Comparators: <, <=, =, >=, >, !=
  • short — ~D, ~n, ~y, ~d — Comparators: <, > — Ranges: a-b (>=a&<=b), -b (<=b), a- (>=a)

🫶 Booleans

tag (true if track has tags), stream (true if track is a stream)

For short expressions: ~T and ~s

🎀 Defining Filters

Filters can be defined with the fset command. User defined filters appear in the filters view (6).

Create a new filter which name is ogg and value filename="*.ogg"

:fset ogg=filename="*.ogg"

Filter ogg and mp3 files from the 90s. Note the use of user defined filter ogg.

:fset 90s-ogg-mp3=date>=1990&date<2000&(ogg|filename="*.mp3")

✨ Activating Filters

factivate changes the visible contents of the library (views 1-2).

Activate user defined filters ogg and missing-tags

:factivate ogg missing-tags

Like above but negate value of ogg filter.

:factivate !ogg missing-tags

Alternatively, you can filter by pressing space in view 6, then activate them by pressing enter.

💖 Throw-away Filters

The live-filter and filter commands are useful when you want to use a filter without saving it. It changes the visible contents of the library (views 1-2). filter unactivates all filters in the filters view, while live-filter is applied in addition to all currently activated filters. It persists even after leaving command mode.

Filter all rock (anything with rock in genre tag) music from 80s-

:filter date>=1980&genre="*rock*"
:filter ~y1980-~grock

Filter all artists/albums/titles containing "sleepwalking"

:live-filter sleepwalking

🌈 Selecting Tracks Matching a Filter

Mark (select) all tracks with duration less than 2 minutes

:mark duration<120

Mark (select) all tracks which have been played at least once

:mark play_count>=1

These commands work in views 2-4.

📁 FILES 📁

cmus reads its configuration from 3 different places in the following order:

  • $XDG_CONFIG_HOME/cmus/autosave — This file is automatically created and overwritten by cmus on exit, so it should not be modified by hand.
  • /usr/share/cmus/rc — This file contains the default configuration.

If the autosave file did exist, this file is read instead.

  • $XDG_CONFIG_HOME/cmus/rc — This file is the static configuration file.

This file is read immediately after the autosave file, and is never modified by cmus. You can override auto-saved settings in this file. This file is not limited to options; it can contain other commands too.

🎨 Color Schemes

Color schemes (*.theme) are located in /usr/share/cmus or $XDG_CONFIG_HOME/cmus. You can switch them using the :colorscheme command with the basename of the theme file.

Note: Colors are not automatically updated when the theme file changes since they are saved in the autosave file.

🖼️ Examples

Example status display scripts (see status_display_program) can be found in /usr/share/doc/cmus/examples.

🌍 ENVIRONMENT 🌍

  • CMUS_CHARSET — Override the character set used by cmus (default: locale charmap).
  • CMUS_HOME — Override the config directory (default: $XDG_CONFIG_HOME/cmus).
  • CMUS_SOCKET — Override the socket path (default: $XDG_RUNTIME_DIR/cmus-socket).
  • HOME — Full path of the user's home directory.
  • http_proxy — URI of the proxy to use for HTTP requests.
  • USER — Name of the user running cmus.
  • USERNAME — Fallback for USER.

📚 Library Environment Variables

cmus supports using environment variables to allow the library, cache, and playlists to be relocated or synced. The environment variables to use are specified using the pl_env_vars configuration option, which takes effect when exiting cmus.

A good starting point is :set pl_env_vars=HOME. This will allow the .cmus directory to be shared between devices or users. Additional environment variables can be appended (delimited with commas) to pl_env_vars to redirect specific paths. The environment variables must contain absolute paths to be used. The last matching directory prefix will be used.

If a file does not exist, it will be treated the same way as missing files usually are. If the file is in the cache, it will be preserved, and an error will be displayed upon playback. If the file is not in the cache, it will be removed from playlists and the library. There is one special exception: if a file is missing due to the environment variable being invalid/empty/unset, but it is still in the cache, it will be preserved in the cache as-is, in addition to being preserved in the library like usual.

When using :save/:load and in the on-disk library/cache/playlists, the paths will be stored with the environment variable delimited using the character \x1F, which is the invisible ASCII unit separator.

This feature can also be used to quickly move a library to a different location while preserving all metadata, playlists, and the play counts. To do this, set an environment variable for each base path you want to change, set pl_env_vars to the list of environment variables, restart cmus, change the environment variables, restart cmus, unset pl_env_vars, then restart cmus again.

If a library using pl_env_vars is opened with a version of cmus not supporting it, tracks referenced with environment variables will be forgotten. To restore the on-disk files to be compatible with older cmus versions, just unset pl_env_vars, and restart cmus. This will restore the paths for all defined environment variables to their actual path.

It is safe to change pl_env_vars from outside cmus since this variable is applied when cmus exits.

🦋 D-Bus Interface (MPRIS) 🦋

cmus provides a D-Bus interface following the Media Player Remote Interfacing Specification (MPRIS) v2:

https://www.freedesktop.org/wiki/Specifications/mpris-spec/

It exposes the /org/mpris/MediaPlayer2 object path with the interfaces org.mpris.MediaPlayer2 and org.mpris.MediaPlayer2.Player. The unique bus name is org.mpris.MediaPlayer2.cmus.

Metadata fields follow the naming convention of the specification:

https://www.freedesktop.org/wiki/Specifications/mpris-spec/metadata/

Additionally, the cmus:stream_title field is exposed if appropriate.

💀 BUGS 💀

The file exists only if you configured cmus with the maximum debug level (./configure DEBUG=2).

After a crash, the last lines of ~/cmus-debug.txt may contain useful information.

Feature requests and bug reports should go to the GitHub issue tracker:

https://github.com/cmus/cmus/issues

👀 SEE ALSO 👀

cmus-tutorial(7), cmus-remote(1)

👑 AUTHORS 👑

cmus was mainly written by Timo Hirvonen <tihirvon@gmail.com>. Other contributors are listed in the AUTHORS file.

This man page was written by Frank Terbeck <ft@bewatermyfriend.org>, Timo Hirvonen <tihirvon@gmail.com>, Clay Barnes <clay.barnes@gmail.com>, and Patrick Gaskin <patrick@pgaskin.net>.

okay bestie that's the whole page! it's giving cmus, 31/01/2010, CMUS(1) 💖✨

📦 where this page comes from