.TH CMUS 1 31/01/2010 cmus .nh .ad l .SH NAME cmus \- C* Music Player .SH SYNOPSIS cmus [\fBoptions\fR] .SH 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 \fBcmus\-remote\fR(1). .SH OPTIONS \-\-listen ADDR .RS Listen on ADDR (UNIX socket) instead of \fI$CMUS_SOCKET\fR or \fI$XDG_RUNTIME_DIR/cmus\-socket\fR. ADDR must be a UNIX socket or host[:port]. .RE .RS \fBWARNING\fR: 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. .RE .RS NOTE: Don't use this option to run multiple instances as the same user. Doing so would corrupt the track metadata cache. .RE \-\-passwd PASSWD .RS Set the password for TCP/IP connections. Required if listening on host[:port]. Used in conjunction with \-\-listen. .RE \-\-plugins .RS List available plugins and exit. .RE \-\-show\-cursor .RS Always display the cursor. This is useful for screen readers. .RE \-\-help .RS Display usage information and exit. .RE \-\-version .RS Display version information and exit. .RE .SH VIEWS There are 7 views in cmus. Press keys 1\-7 to change active view. Library view (1) .RS Displays all tracks in the \fBlibrary\fR. Tracks are sorted and displayed in a tree grouped by artist/album. Artist sorting is done alphabetically. Albums are sorted by year. .RE Sorted library view (2) .RS Displays the same content as view 1, but as a simple list automatically sorted by user criteria. .RE Playlist view (3) .RS Displays editable playlists with optional sorting. .RE Play Queue view (4) .RS 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. .RE Browser (5) .RS Displays the directory browser. In this view, music from the filesystem can be added to the library, active playlist, or queue. .RE Filters view (6) .RS Lists user\-defined filters. .RE Settings view (7) .RS Lists keybindings, unbound commands and options. Remove bindings with \fBD\fR or \fBdel\fR, change bindings and variables with \fBenter\fR, and toggle variables with \fBspace\fR. .RE .SH 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 \fB:\fR. To execute a command, press \fBENTER\fR, and to cancel, press \fBESC\fR or \fBCTRL\-C\fR. Use up/down arrows to browse the command history. Use \fBTAB\fR 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: .RS .nf # 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 .fi .RE .SH SEARCHING Search mode works like the command mode. To enter search mode, press \fB/\fR and type the query then press \fBENTER\fR. Press \fBn\fR to move to the next result or \fBN\fR for the previous one. Type \fB?\fR to search backwards. In views 1\-4 the query is matched against the artist, album and title tags. Type \fB//WORDS\fR or \fB??WORDS\fR 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. .SH PLAYLIST EDITING .SS 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 \fBSPACE\fR. Marked tracks appear with a gray background. You can only mark tracks in the list views (2\-4). .SS Copying Tracks Between Views You can copy marked or selected tracks in views 1\-5. .TP \fBa\fR copy tracks to the library (1\-2) .TP \fBy\fR copy tracks to the marked playlist (3) .TP \fBe\fR append tracks to the play queue (4) .TP \fBE\fR prepend tracks to the play queue (4) .SS 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 \fBlib_sort\fR and \fBpl_sort\fR options). Pressing \fBp\fR moves marked tracks to the position immediately after the selected track. \fBP\fR moves them to the position immediately before the selected track. If there are no marked tracks, the selected track is moved down (\fBp\fR) or up (\fBP\fR). Note that changing active filters in view 2 reloads it, losing any changes made to the track order. .SS Removing Tracks Press \fBD\fR or \fBdelete\fR 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. .SH 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: .nf aaa_mode & play_sorted & play_library | continue follow repeat shuffle .fi NOTE: \fBaaa_mode\fR and \fBplay_sorted\fR will be only displayed if \fBplay_library\fR is \fBtrue\fR because these are meaningless when playing the playlists (view 3). Pressing \fBm\fR, \fBo\fR, \fBM\fR, \fBC\fR, \fBr\fR and \fBs\fR should make it easier to understand what these fields mean. See the CONFIGURATION OPTIONS section for more information about these options. .SH KEYBINDINGS Here's list of default keybindings. To change them, see the \fBunbind\fR and \fBbind\fR commands in the COMMANDS section. .SS Common: Playback .nf 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 .fi .SS Common: Setting Toggles .nf 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 .fi .SS Common: Commands .nf q quit \-i ^C echo Type :quit to exit cmus. I echo {} ! push shell .fi .SS Common: View/Window Navigation .nf 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 .fi .SS Common: Navigation .nf ^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 .fi .SS Common: Selection .nf 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 .fi .SS Common: Filters .nf / search\-start ? search\-b\-start n search\-next N search\-prev F push filter L push live\-filter .fi .SS File Browser .nf space win\-activate backspace browser\-up i toggle show_hidden u win\-update .fi .SH LIBRARY VIEW SORTING The library view (the tree\-like one; not the sorted library view, which is configured with lib_sort \- see \fICONFIGURATION OPTIONS\fR), 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 \fBTPE2\fR frame is set, it will be used instead of the real artist name. Otherwise, cmus determines if the album is a compilation (if \fBalbumartist\fR or \fBartist\fR are set to \fBVarious Artists\fR, \fBVarious\fR, \fBVA\fR, or \fBV/A\fR; or if \fBcompilation\fR or \fBpartofacompilation\fR are set to a truthy value; or if the ID3v2 \fBTCMP\fR frame is set). If so, the artist is named \fB\fR. Note: If the filename is a URL, the artist/album tags are set to \fB\fR. If it is a file, cmus sets the artist and/or album tags to \fB\fR 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 \fBdiscnumber\fR, \fBtracknumber\fR, then filename (not the track name). .SH 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] .RS Adds file/dir/url/playlist to the specified view or the current view. .TP \-l add to library .TP \-p add to playlist .TP \-q add play queue .TP \-Q prepend to play queue .RE .RS Supported files are based on the loaded input plugins. .RE .RS Supported URLs: Shoutcast (\fIhttp://\fR...), CDDA (\fIcdda://\fR...). .RE .RS Supported playlist types: plain, .m3u, .pls. .RE bind [\-f] .RS Adds a key binding. .TP \-f overwrite existing binding .RE .RS Valid contexts: common (i.e. all views), library (1\-2), playlist (3), queue (4), browser (5), filters (6) .RE .RS There's one context for each view. Common is a special context on which bound keys work in every view. .RE .RS You can override specific keys in common context for a view. For example \fBi\fR selects the current track in views 1\-3 but in browser it is overridden to toggle showing of hidden files. .RE .RS When setting custom bindings in \fI$XDG_CONFIG_HOME/cmus/rc\fR, 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. .RE .RS Hint: You can press \fBtab\fR from command mode to expand contexts, keys, and commands. .RE browser\-up (\fBbackspace\fR) .RS Navigates the browser view to the parent directory (5). This command only makes sense to be bound to the \fBbrowser\fR key context although it's possible to use this even if browser view is not active. .RE cd [directory] .RS Changes the current working directory. Also changes the directory displayed in the browser view. .RE clear [\-l] [\-p] [\-q] .RS Removes all tracks from a single view. .TP \-l clear library .TP \-p clear playlist .TP \-q clear play queue .RE .RS If a view is not specified, the current view is used. .RE colorscheme .RS Changes the color scheme. Color schemes are found in \fI/usr/share/cmus/\fR or \fI$XDG_CONFIG_HOME/cmus/\fR and have the extension \fB.theme\fR. .RE echo ... .RS Displays the arguments on the command line. .RE .RS \fB{}\fR it is replaced with file name of the first selected track. .RE factivate ... .RS 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. .RE .RS Prefix a filter name with \fB!\fR to negate it. .RE filter .RS Temporarily filters a library view. The filter is not saved (use \fBfset\fR and \fBfactivate\fR for that). .RE fset = .RS Defines or replaces an existing filter and adds it to the filters view (6). .RE help .RS Shows information about help files. .RE invert .RS Inverts the marking of tracks in playlist and queue views. See \fBmark\fR and \fBunmark\fR. .RE live\-filter .RS Like filter, but uses simple filters and shows a preview as you type. It persists even after leaving command mode. .RE load [\-l] [\-p] .RS Loads a playlist to a view. .TP \-l load to library views .TP \-p load to playlist view .RE .RS If a view is not specified, the current view is used. .RE lqueue [NUM] .RS Queues NUM (default 1) random albums from the library. Also see \fBtqueue\fR. .RE mark .RS Marks tracks in playlist and queue view using a filter expression. .RE mute .RS Toggles mute for the sound output. .RE pl\-create .RS Creates a new playlist. .RE pl\-export .RS Exports the currently selected playlist. The file will be overwritten if it exists. .RE pl\-import [filename] .RS Imports a playlist into the playlist view. The argument can be omitted in the file browser view. .RE pl\-rename .RS Renames the selected playlist. .RE player\-next (\fBb\fR) .RS Skips to the next track. .RE player\-next\-album (\fBB\fR) .RS Skips to the next album. If \fBshuffle\fR=\fItracks\fR or a playlist is active, skips to the next track. .RE player\-pause (\fBc\fR) .RS Toggles pause. .RE player\-pause\-playback .RS Pauses if currently playing. .RE player\-play [filename] (\fBx\fR) .RS Plays the given track, or, if none is specified, [re]plays the current track from the beginning. .RE player\-prev (\fBz\fR) .RS Skips to the previous track. .RE player\-prev\-album (\fBZ\fR) .RS Skips to the previous album. If \fBshuffle\fR=\fItracks\fR or a playlist is active, skips to the previous track. .RE player\-stop (\fBv\fR) .RS Stops playback. .RE prev\-view .RS Goes to the previously used view. .RE left\-view .RS Goes to the to view to the left of current one (e.g. view 4 \-> view 3) .RE right\-view .RS Goes to view to the right of current one (e.g. view 3 \-> view 4). .RE push [text] .RS Enters command mode with the command line pre\-set to text. Example: .RE .RS .RS bind common w push filter artist= .RE .RE .RS 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. .RE .RS This command can only be used from a keybinding. .RE pwd .RS Prints the current working directory. .RE quit [\-i] (\fBq\fR, \fB:wq\fR) .RS Exits cmus. .TP \-i ask before exiting .RE raise\-vte .RS Raises the virtual terminal emulator window. Only works within a X session. .RE rand .RS Randomizes (shuffles) the tracks in the library, playlist or queue view. .RE refresh (\fB^L\fR) .RS Redraws the terminal window. .RE reshuffle .RS Reshuffles the shuffle lists for both library and playlist views. .RE run .RS Runs a command for the marked tracks OR the selected one if none marked. .RE .RS By default file names are appended to the command. If the command contains \fB{}\fR it is replaced with list of filenames. .RE .RS Note: In view 1 you can run a command for all files in the selected album or artist. .RE save [\-e] [\-l] [\-L] [\-p] [\-q] [file] (\fB:w\fR) .RS Saves the contents of a view to a playlist file. In extended mode (\-e), also saves track metadata. .TP \-l save library views .TP \-L save filtered library views .TP \-p save playlist view .TP \-q save queue view .RE .RS If no view is specified, the current one is used. .RE .RS If no filename given the old filename is used. "\-" outputs to stdout (works only remotely). .RE search\-b\-start .RS Enters backwards search mode. Cannot be used directly from command mode. .RE .RS See \fBsearch\-start\fR. .RE search\-next (\fBn\fR) .RS If there is an active search, goes to the next match in the current view. See \fBSEARCHING\fR above. .RE search\-prev (\fBN\fR) .RS If there is an active search, goes to the previous match in the current view. See \fBSEARCHING\fR above. .RE search\-start .RS Enters search mode. Cannot be used directly from command mode. .RE .RS This is similar to live\-filter, except it is temporary and only selects the current match rather than filtering the entire view. .RE seek [+\-]([mh] | [HH:]MM:SS) .RS 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. .RE .RS Seek 1 minute backward .RS :seek \-1m .RE .RE .RS Seek 5 seconds forward .RS :seek +5 .RE .RE .RS Seek to absolute position 1h .RS :seek 1h .RE .RE .RS Seek 90 seconds forward .RS :seek +1:30 .RE .RE set