CMUS(1) General Commands Manual CMUS(1) 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). 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. --passwd PASSWD Set the password for TCP/IP connections. Required if listening on host[:port]. Used in conjunction with --listen. --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. 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). 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 | 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 mouse_scroll_up_bar seek +5 mouse_scroll_down_bar seek -5 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 to exit cmus. I echo {} ! push shell 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 L push live-filter File Browser space win-activate backspace browser-up i toggle show_hidden u win-update LIBRARY VIEW SORTING 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. 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 . Note: If the filename is a URL, the artist/album tags are set to . If it is a file, cmus sets the artist and/or album tags to 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 and default key bindings are (parenthesized). add [-l] [-p] [-q] [-Q] 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] 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 Changes the color scheme. Color schemes are found in /usr/share/cmus/ or $XDG_CONFIG_HOME/cmus/ and have the extension .theme. echo ... Displays the arguments on the command line. {} it is replaced with file name of the first selected track. factivate ... 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 Temporarily filters a library view. The filter is not saved (use fset and factivate for that). fset = 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 Like filter, but uses simple filters and shows a preview as you type. It persists even after leaving command mode. load [-l] [-p] Loads a playlist to a view. -l load to library views -p load to playlist view If a view is not specified, the current view is used. lqueue [NUM] Queues NUM (default 1) random albums from the library. Also see tqueue. mark Marks tracks in playlist and queue view using a filter expression. mute Toggles mute for the sound output. pl-create Creates a new playlist. pl-export 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 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 Goes to the to view to the left of current one (e.g. view 4 -> view 3) right-view Goes to view to the right of current one (e.g. view 3 -> view 4). 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 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 [+-]([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